feat(island): count badge, date time, detail row, filter chips, spinner sizes, carousel nav buttons

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-08 22:36:22 +04:00
parent b85b05861f
commit a668b17590
27 changed files with 396 additions and 19 deletions

View File

@ -0,0 +1,33 @@
import { number } from '@lumina/tools/format';
import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn';
import type { CountBadgeProps } from './types';
/**
* An unread count on an icon, such as the bell's (U5 ۲.۲): white digits on danger, «۳», «۲۴»,
* then «۹۹+». Nothing at 0. Decorative: the control's accessible name says the count, so the badge
* is hidden from screen readers. The caller places it, usually at the icon's top end.
*/
export function CountBadge({
count,
cap = 99,
className,
...props
}: CountBadgeProps) {
if (count <= 0) return null;
return (
<Element
tag="span"
aria-hidden
className={cn(
'inline-grid h-4.5 min-w-4.5 place-items-center rounded-full bg-danger-solid px-1 text-micro font-bold text-text-on-action tabular-nums',
className,
)}
{...props}
>
{count > cap ? `${number(cap)}+` : number(count)}
</Element>
);
}

View File

@ -0,0 +1,2 @@
export { CountBadge } from './CountBadge';
export type { CountBadgeProps } from './types';

View File

@ -0,0 +1,11 @@
import type { ComponentPropsWithRef } from 'react';
export type CountBadgeProps = Omit<
ComponentPropsWithRef<'span'>,
'children'
> & {
/** How many; nothing shows at 0. */
count: number;
/** Above it the badge reads «۹۹+», so it never holds more than two digits and a plus. */
cap?: number;
};

View File

@ -0,0 +1,15 @@
import { date, time } from '@lumina/tools/format';
import { Separator } from '../separator';
import type { DateTimeProps } from './types';
/** A Shamsi day and its minute, apart: «۲ تیر ۱۴۰۴ | ۱۴:۲۳». */
export function DateTime({ value }: DateTimeProps) {
return (
<>
{date(value, { time: false })}
<Separator />
{time(value)}
</>
);
}

View File

@ -0,0 +1,2 @@
export { DateTime } from './DateTime';
export type { DateTimeProps } from './types';

View File

@ -0,0 +1,4 @@
export type DateTimeProps = {
/** An ISO date-time. */
value: string;
};

View File

@ -1,17 +1,18 @@
import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn';
import type { SpinnerProps } from './types';
import { spinnerVariants } from './variants';
/** A ring that turns while one action is in flight. Never for loading a page: use Skeleton. */
export function Spinner({ className, ...props }: SpinnerProps) {
/**
* A ring that turns while one action is in flight, or on the one screen that only says "wait".
* Never for loading a page: use Skeleton.
*/
export function Spinner({ size, className, ...props }: SpinnerProps) {
return (
<Element
tag="span"
aria-hidden
className={cn(
'inline-block size-[1.125rem] flex-none animate-spin rounded-full border-2 border-current border-e-transparent',
className,
)}
className={cn(spinnerVariants({ size }), className)}
{...props}
/>
);

View File

@ -1,2 +1,3 @@
export { Spinner } from './Spinner';
export type { SpinnerProps } from './types';
export { spinnerVariants } from './variants';

View File

@ -1,3 +1,7 @@
import type { VariantProps } from 'class-variance-authority';
import type { ComponentPropsWithRef } from 'react';
export type SpinnerProps = Omit<ComponentPropsWithRef<'span'>, 'children'>;
import type { spinnerVariants } from './variants';
export type SpinnerProps = Omit<ComponentPropsWithRef<'span'>, 'children'> &
VariantProps<typeof spinnerVariants>;

View File

@ -0,0 +1,19 @@
import { cva } from 'class-variance-authority';
export const spinnerVariants = cva(
'inline-block flex-none animate-spin rounded-full',
{
variants: {
size: {
/** Inside a button or beside a label, in the text's colour. */
inline: 'size-[1.125rem] border-2 border-current border-e-transparent',
/**
* A screen that exists only to say "wait", such as «در حال تأیید پرداخت...»: 40px, a muted
* ring with the brand arc.
*/
page: 'size-10 border-3 border-action-primary-muted border-e-action-primary',
},
},
defaultVariants: { size: 'inline' },
},
);

View File

@ -13,6 +13,8 @@ export { Checkbox, checkboxVariants } from './atoms/checkbox';
export type { CheckboxProps } from './atoms/checkbox';
export { Chip, chipVariants } from './atoms/chip';
export type { ChipProps, ChipSize } from './atoms/chip';
export { CountBadge } from './atoms/count-badge';
export type { CountBadgeProps } from './atoms/count-badge';
export { Countdown, countdownTone } from './atoms/countdown';
export type {
CountdownKind,
@ -67,9 +69,11 @@ export {
skeletonVariants,
} from './atoms/skeleton';
export type { SkeletonProps, SkeletonRegionProps } from './atoms/skeleton';
export { DateTime } from './atoms/date-time';
export type { DateTimeProps } from './atoms/date-time';
export { Separator } from './atoms/separator';
export type { SeparatorProps } from './atoms/separator';
export { Spinner } from './atoms/spinner';
export { Spinner, spinnerVariants } from './atoms/spinner';
export { useCountdown } from './hooks/use-countdown';
export type { CountdownOptions } from './hooks/use-countdown';
export { useOnline } from './hooks/use-online';
@ -113,12 +117,19 @@ export { ChipGroup } from './molecules/chip-group';
export type { ChipGroupOption, ChipGroupProps } from './molecules/chip-group';
export { ChoiceCard, choiceCardVariants } from './molecules/choice-card';
export type { ChoiceCardProps } from './molecules/choice-card';
export { DetailRow, detailRowVariants } from './molecules/detail-row';
export type { DetailRowProps } from './molecules/detail-row';
export { EmptyState } from './molecules/empty-state';
export type { EmptyStateProps, EmptyStateTone } from './molecules/empty-state';
export { ERROR_KIND_STYLES, ErrorState } from './molecules/error-state';
export type { ErrorKind, ErrorStateProps } from './molecules/error-state';
export { FactCard } from './molecules/fact-card';
export type { FactCardProps } from './molecules/fact-card';
export { FilterChips } from './molecules/filter-chips';
export type {
FilterChipOption,
FilterChipsProps,
} from './molecules/filter-chips';
export { FormSection } from './molecules/form-section';
export type { FormSectionProps } from './molecules/form-section';
export { LockedTeaser } from './molecules/locked-teaser';

View File

@ -0,0 +1,29 @@
import { FlexBox } from '../../atoms/flex-box';
import { Typography } from '../../atoms/typography';
import { Element } from '../../primitives/element';
import type { DetailRowProps } from './types';
import { detailRowVariants } from './variants';
/**
* One line of a `<dl>`, such as a receipt or a payment's detail: the label at the start, its
* value at the end, on one baseline.
*/
export function DetailRow({ label, children, size }: DetailRowProps) {
return (
<FlexBox
alignItems="items-baseline"
justifyContent="justify-between"
gap="gap-3"
className={detailRowVariants({ size })}
>
<Element tag="dt">
<Typography tag="span" variant="body-sm" color="secondary">
{label}
</Typography>
</Element>
<Element tag="dd" className="m-0 text-end font-semibold">
{children}
</Element>
</FlexBox>
);
}

View File

@ -0,0 +1,3 @@
export { DetailRow } from './DetailRow';
export type { DetailRowProps } from './types';
export { detailRowVariants } from './variants';

View File

@ -0,0 +1,10 @@
import type { VariantProps } from 'class-variance-authority';
import type { ReactNode } from 'react';
import type { detailRowVariants } from './variants';
export type DetailRowProps = VariantProps<typeof detailRowVariants> & {
label: ReactNode;
/** The value, at the end. */
children: ReactNode;
};

View File

@ -0,0 +1,12 @@
import { cva } from 'class-variance-authority';
/** `sm` for a receipt card, `md` for a detail sheet's divided list. */
export const detailRowVariants = cva('', {
variants: {
size: {
sm: 'py-1.5',
md: 'py-2',
},
},
defaultVariants: { size: 'md' },
});

View File

@ -0,0 +1,64 @@
import { useId } from 'react';
import { chipVariants } from '../../atoms/chip';
import { FlexBox } from '../../atoms/flex-box';
import { Typography } from '../../atoms/typography';
import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn';
import type { FilterChipsProps } from './types';
/**
* A one-of filter as a wrapping row of chips, such as a list's status (U4 ۳.۱): it applies at
* once, with no apply button. A named radiogroup of real radios, so Tab reaches the chosen chip
* and the arrow keys move the choice. The chosen chip fills brand; unlike a multiple-choice Chip
* it has no check, since exactly one is always chosen.
*/
export function FilterChips<T extends string>({
options,
value,
onChange,
label,
size = 'md',
disabled = false,
className,
}: FilterChipsProps<T>) {
const name = useId();
return (
<FlexBox
tag="fieldset"
role="radiogroup"
aria-label={label}
disabled={disabled}
wrap="flex-wrap"
gap="gap-2"
className={cn('m-0 min-w-0 border-0 p-0', className)}
>
{options.map((option) => (
<FlexBox
key={option.value}
tag="label"
display="inline-flex"
alignItems="items-center"
className={cn(
chipVariants({ selected: option.value === value, size }),
'relative has-[input:focus-visible]:focus-ring',
)}
>
<Element
tag="input"
type="radio"
name={name}
value={option.value}
checked={option.value === value}
onChange={() => onChange(option.value)}
className="pointer-events-none absolute m-0 size-px opacity-0"
/>
<Typography tag="span" variant="label" color="inherit">
{option.label}
</Typography>
</FlexBox>
))}
</FlexBox>
);
}

View File

@ -0,0 +1,2 @@
export { FilterChips } from './FilterChips';
export type { FilterChipOption, FilterChipsProps } from './types';

View File

@ -0,0 +1,20 @@
import type { ReactNode } from 'react';
import type { ChipSize } from '../../atoms/chip';
export type FilterChipOption<T extends string> = { value: T; label: ReactNode };
export type FilterChipsProps<T extends string> = {
/** In reading order, such as «همه» · «موفق» · «در حال بررسی» · «ناموفق». */
options: readonly FilterChipOption<T>[];
/** The one shown now. */
value: T;
/** Called with the chip picked by a press or the arrow keys; never for the chosen one. */
onChange: (value: T) => void;
/** The group's accessible name, such as «وضعیت». */
label: string;
/** `md` (44px) on a page, `sm` (36px) in a compact row. */
size?: ChipSize;
disabled?: boolean;
className?: string;
};

View File

@ -5,7 +5,8 @@ import type { MediaCarouselProps } from './types';
/**
* A post's images. One shows full width at its own ratio, letterboxed at 400px on
* `surface-sunken`; 2–4 swipe in 280px slides with dots and a «۱ / ۳» count. Server-renderable:
* `surface-sunken`; 2–4 swipe in 280px slides with dots and a «۱ / ۳» count, and from 480px wide
* also move with ‹ › buttons on the image. Server-renderable:
* a single image ships no JavaScript, and only the swipe track is a client component, so every
* prop it takes is serializable except `onOpen`, which only a client caller can pass.
*/
@ -15,6 +16,8 @@ export function MediaCarousel({
href,
onOpen,
label,
previousLabel,
nextLabel,
className,
}: MediaCarouselProps) {
const shown = items.slice(0, MAX_MEDIA);
@ -42,6 +45,8 @@ export function MediaCarousel({
href={href}
onOpen={onOpen}
label={label}
previousLabel={previousLabel}
nextLabel={nextLabel}
className={className}
/>
);

View File

@ -0,0 +1,30 @@
import { GridBox } from '../../../atoms/grid-box';
import { Icon } from '../../../atoms/icon';
import type { MediaNavButtonProps } from '../types';
import { mediaNavVariants } from '../variants';
/** A ‹ › button on the track; its chevron points the way it moves, flipped in LTR. */
export function MediaNavButton({
side,
label,
isDisabled,
onClick,
}: MediaNavButtonProps) {
return (
<GridBox
tag="button"
type="button"
justifyItems="justify-items-center"
alignItems="items-center"
aria-label={label}
aria-disabled={isDisabled || undefined}
onClick={isDisabled ? undefined : onClick}
className={mediaNavVariants({ side })}
>
<Icon
name={side === 'previous' ? 'chevron-right' : 'chevron-left'}
className="ltr:-scale-x-100"
/>
</GridBox>
);
}

View File

@ -46,7 +46,7 @@ export function MediaSlide({
className={cn(
box,
'actionable:cursor-zoom-in',
// A slide's ring would be clipped by the scrolling track, so the track's frame draws it.
// A slide's ring would be clipped by the scrolling track, so the track draws it.
single ? 'focus-visible:focus-ring' : 'outline-none',
)}
>

View File

@ -1,19 +1,25 @@
'use client';
import { number } from '@lumina/tools/format';
import { useState } from 'react';
import type { UIEvent } from 'react';
import { useRef, useState } from 'react';
import type { KeyboardEvent, UIEvent } from 'react';
import { FlexBox } from '../../../atoms/flex-box';
import { Typography } from '../../../atoms/typography';
import { Element } from '../../../primitives/element';
import { cn } from '../../../tools/cn';
import type { MediaCarouselProps } from '../types';
import { mediaDotVariants } from '../variants';
import { MediaNavButton } from './MediaNavButton';
import { MediaSlide } from './MediaSlide';
const isRtl = (node: HTMLElement) => getComputedStyle(node).direction === 'rtl';
/**
* 2–4 images in a native swipe (scroll snap), with a «۱ / ۳» chip and a dot per image. The only
* client part of a post: it follows the scroll to light the current dot and count.
* 2–4 images in a native swipe (scroll snap), with a «۱ / ۳» count and a dot per image. From 480px
* wide, ‹ › buttons on the image move it too, and ← → on a focused slide. Moving never opens the
* Lightbox: only a tap on an image does. The only client part of a post: it follows the scroll to
* light the current dot and count.
*/
export function MediaTrack({
items,
@ -21,9 +27,12 @@ export function MediaTrack({
href,
onOpen,
label,
previousLabel,
nextLabel,
className,
}: MediaCarouselProps) {
const [current, setCurrent] = useState(0);
const trackRef = useRef<HTMLDivElement>(null);
const count = items.length;
// scrollLeft is negative in RTL, so its size gives the slide either way.
@ -33,18 +42,52 @@ export function MediaTrack({
setCurrent(Math.min(count - 1, index));
};
// Only scrolls: `handleScroll` then moves the dots and the count.
const goTo = (index: number) => {
const track = trackRef.current;
if (!track) return;
const reduced = window.matchMedia(
'(prefers-reduced-motion: reduce)',
).matches;
track.scrollTo({
left: (isRtl(track) ? -1 : 1) * index * track.clientWidth,
behavior: reduced ? 'auto' : 'smooth',
});
};
// ← is next in RTL, as in the Lightbox. Focus moves with the image, so Enter opens the one shown.
const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
const track = event.currentTarget;
const slides = Array.from(track.children) as HTMLElement[];
const from = slides.indexOf(event.target as HTMLElement);
if (from === -1) return;
const [next, previous] = isRtl(track)
? ['ArrowLeft', 'ArrowRight']
: ['ArrowRight', 'ArrowLeft'];
const step = event.key === next ? 1 : event.key === previous ? -1 : 0;
if (step === 0) return;
event.preventDefault();
const to = Math.min(Math.max(from + step, 0), count - 1);
if (to === from) return;
slides[to].focus({ preventScroll: true });
goTo(to);
};
return (
<FlexBox
tag="section"
direction="flex-col"
gap="gap-2"
aria-label={label}
className={className}
className={cn('@container', className)}
>
<Element className="relative rounded-md has-[:focus-visible]:focus-ring">
<Element className="relative">
<FlexBox
ref={trackRef}
onScroll={handleScroll}
className="snap-x snap-mandatory overflow-x-auto overscroll-x-contain rounded-md bg-surface-sunken [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
onKeyDown={handleKeyDown}
// A slide's ring would be clipped by the scroll, so the track draws it; not the buttons'.
className="snap-x snap-mandatory overflow-x-auto overscroll-x-contain rounded-md bg-surface-sunken [scrollbar-width:none] has-[:focus-visible]:focus-ring [&::-webkit-scrollbar]:hidden"
>
{items.map((item, index) => (
<MediaSlide
@ -59,12 +102,28 @@ export function MediaTrack({
/>
))}
</FlexBox>
{/* Each slide button already says «۱ از ۳»; the chip is for the eye only. */}
{previousLabel && nextLabel && (
<>
<MediaNavButton
side="previous"
label={previousLabel}
isDisabled={current === 0}
onClick={() => goTo(current - 1)}
/>
<MediaNavButton
side="next"
label={nextLabel}
isDisabled={current === count - 1}
onClick={() => goTo(current + 1)}
/>
</>
)}
<Typography
tag="span"
variant="micro"
color="on-action"
aria-hidden
aria-live="polite"
aria-atomic
className="absolute end-2 top-2 rounded-sm bg-scrim-chip px-2"
>
<Element tag="bdi" dir="ltr">

View File

@ -26,6 +26,12 @@ export type MediaCarouselProps = {
onOpen?: (index: number) => void;
/** The swipe section's accessible name, such as «تصاویر پست». */
label?: string;
/**
* The ‹ › buttons' names, «تصویر قبلی» and «تصویر بعدی». The buttons show only with both, on a
* carousel at least 480px wide.
*/
previousLabel?: string;
nextLabel?: string;
className?: string;
};
@ -40,3 +46,12 @@ export type MediaSlideProps = {
onOpen?: (index: number) => void;
className?: string;
};
export type MediaNavButtonProps = {
/** Previous sits at inline-start, next at inline-end. */
side: 'previous' | 'next';
label: string;
/** At the first or last image: frozen, but it keeps focus. */
isDisabled: boolean;
onClick: () => void;
};

View File

@ -33,3 +33,20 @@ export const mediaDotVariants = cva(
defaultVariants: { active: false },
},
);
/**
* A 44px ‹ › control on the image, vertically centred. Hidden until the carousel (its `@container`)
* is 480px wide, so phones swipe. Ends use `aria-disabled`, so a focused button keeps focus when
* it runs out.
*/
export const mediaNavVariants = cva(
'absolute top-1/2 z-1 hidden size-touch-target -translate-y-1/2 rounded-full bg-image-control text-text-primary shadow-2 transition-[opacity,background-color] duration-120 ease-standard @min-[480px]:grid focus-visible:focus-ring actionable:cursor-pointer actionable:hover:bg-surface aria-disabled:frozen',
{
variants: {
side: {
previous: 'start-3',
next: 'end-3',
},
},
},
);

View File

@ -46,6 +46,8 @@ export function PostContent({
href={href}
onOpen={onImageClick}
label={labels.images}
previousLabel={labels.previousImage}
nextLabel={labels.nextImage}
className={ABOVE_LINK_CLASS}
/>
)}

View File

@ -65,6 +65,9 @@ export type PostCardLabels = {
* تصویر ۱ از ۳، نمودار طلا».
*/
openSlide?: (n: string, total: string, alt: string) => string;
/** The carousel's ‹ › buttons, «تصویر قبلی» and «تصویر بعدی»; they show only with both. */
previousImage?: string;
nextImage?: string;
/** A locked post's image count, from 2 images: `(n) => <>{n} تصویر</>` → «۳ تصویر». */
imageCount: (count: string) => ReactNode;
/** «اشتراک‌گذاری». */

View File

@ -250,6 +250,8 @@
--inverse-control-hover: rgba(255, 255, 255, 0.2);
/* Counters drawn over images («۱ / ۳»). */
--scrim-chip: rgba(12, 16, 24, 0.64);
/* Controls drawn over images (the post carousel's ‹ ›): near-opaque white pills. */
--image-control: rgba(255, 255, 255, 0.94);
--text-on-action: #ffffff;
--text-link: var(--indigo-600);
--border-subtle: var(--slate-150);
@ -319,6 +321,7 @@
--color-inverse-control: var(--inverse-control);
--color-inverse-control-hover: var(--inverse-control-hover);
--color-scrim-chip: var(--scrim-chip);
--color-image-control: var(--image-control);
--color-text-on-action: var(--text-on-action);
--color-text-link: var(--text-link);
--color-border-subtle: var(--border-subtle);