feat(island): file field, form skeleton, toast details and link start icon

- FileField molecule: one file for a form, with a picker box, thumbnail,
  name, size, remove button, inline error and upload progress.
- SkeletonPreset gains a `form` preset (heading, n fields, button, link).
- Toast takes a second `description` line; showToast takes a stable `id`,
  so a repeated failure replaces its toast instead of stacking.
- Link takes a leading `iconStart`, such as edit before «ویرایش شماره».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-05 20:06:42 +04:00
parent 64048e8224
commit 025c68dd0d
13 changed files with 325 additions and 7 deletions

View File

@ -11,6 +11,7 @@ import { linkVariants } from './variants';
export function Link({
standalone,
icon,
iconStart,
className,
children,
...props
@ -24,6 +25,7 @@ export function Link({
className={cn(linkVariants({ standalone }), className)}
{...props}
>
{iconStart && <Icon name={iconStart} size={18} />}
<Typography tag="span" variant="inherit" color="inherit">
{children}
</Typography>

View File

@ -9,4 +9,6 @@ export type LinkProps = ComponentPropsWithRef<typeof NextLink> &
VariantProps<typeof linkVariants> & {
/** Trailing icon, such as `external` or `chevron-left` ("go to" points left in RTL). */
icon?: IconName;
/** Leading icon, for an action named by its verb, such as `edit` before «ویرایش شماره». */
iconStart?: IconName;
};

View File

@ -0,0 +1,192 @@
'use client';
import { useEffect, useId, useRef } from 'react';
import type { ChangeEvent } from 'react';
import { Button } from '../../atoms/button';
import { FlexBox } from '../../atoms/flex-box';
import { Icon } from '../../atoms/icon';
import { Typography } from '../../atoms/typography';
import { Element } from '../../primitives/element';
import { cn } from '../../tools/cn';
import type { FileFieldProps } from './types';
import { fileDropVariants, filePickedVariants } from './variants';
/**
* One file to send with a form, such as a national ID card image. Empty, the whole dashed box
* opens the picker; picked, it shows a thumbnail (for images), the name and the size with a
* remove button; uploading, a bar with the percent replaces remove. The file stays in memory.
*/
export function FileField({
label,
hint,
file,
size,
onChange,
onBlur,
accept,
error,
progress,
disabled = false,
labels,
id: idProp,
name,
className,
}: FileFieldProps) {
const generatedId = useId();
const id = idProp ?? generatedId;
const messageId = `${id}-message`;
const isInvalid = error != null && error !== false;
const isUploading = progress !== undefined;
const pick = (event: ChangeEvent<HTMLInputElement>) => {
onChange(event.target.files?.[0] ?? null);
// The same file can be picked again after it was removed or rejected.
event.target.value = '';
};
return (
<FlexBox
direction="flex-col"
gap="gap-2"
className={cn('min-w-0', className)}
>
<Typography tag="span" variant="label" id={`${id}-label`}>
{label}
</Typography>
{file ? (
<FlexBox
alignItems="items-center"
gap="gap-3"
className={filePickedVariants({ invalid: isInvalid })}
>
{file.type.startsWith('image/') ? (
<Thumbnail file={file} />
) : (
<Icon
name="upload"
size={24}
className="flex-none text-text-secondary"
/>
)}
<FlexBox direction="flex-col" gap="gap-1" className="min-w-0 flex-1">
<Typography
tag="span"
variant="body-sm"
dir="ltr"
className="truncate text-start font-semibold"
>
{file.name}
</Typography>
{isUploading ? (
<>
<Element
tag="progress"
value={progress}
max={100}
aria-labelledby={`${id}-label`}
className="h-1 w-full appearance-none overflow-hidden rounded-full bg-surface-sunken [&::-moz-progress-bar]:bg-action-primary [&::-webkit-progress-bar]:bg-surface-sunken [&::-webkit-progress-value]:bg-action-primary"
/>
{labels.uploading && (
<Typography tag="span" variant="caption" color="secondary">
{labels.uploading(progress)}
</Typography>
)}
</>
) : (
size != null && (
<Typography tag="span" variant="caption" color="secondary">
{size}
</Typography>
)
)}
</FlexBox>
{!isUploading && (
<Button
variant="ghost"
icon="trash"
label={labels.remove}
disabled={disabled}
onClick={() => onChange(null)}
/>
)}
</FlexBox>
) : (
<FlexBox
tag="label"
htmlFor={id}
direction="flex-col"
alignItems="items-center"
justifyContent="justify-center"
gap="gap-1"
className={fileDropVariants({ invalid: isInvalid, disabled })}
>
<Icon name="upload" size={24} className="text-text-secondary" />
<Typography tag="span" variant="label" color="link">
{labels.pick}
</Typography>
<Typography tag="span" variant="caption" color="secondary">
{labels.rules}
</Typography>
<Element
tag="input"
type="file"
id={id}
name={name}
accept={accept}
disabled={disabled}
onChange={pick}
onBlur={onBlur}
aria-labelledby={`${id}-label`}
aria-invalid={isInvalid || undefined}
aria-describedby={isInvalid || hint != null ? messageId : undefined}
className="sr-only"
/>
</FlexBox>
)}
{isInvalid && error !== true ? (
<FlexBox alignItems="items-center" gap="gap-1">
<Icon name="alert" size={16} className="flex-none text-danger" />
<Typography
tag="span"
variant="caption"
color="danger"
role="alert"
id={messageId}
>
{error}
</Typography>
</FlexBox>
) : (
hint != null && (
<Typography
tag="span"
variant="caption"
color="secondary"
id={messageId}
>
{hint}
</Typography>
)
)}
</FlexBox>
);
}
/** An image file's thumbnail from an object URL, revoked when the file changes or leaves. */
function Thumbnail({ file }: { file: File }) {
const ref = useRef<HTMLImageElement>(null);
useEffect(() => {
const url = URL.createObjectURL(file);
if (ref.current) ref.current.src = url;
return () => URL.revokeObjectURL(url);
}, [file]);
return (
<Element
tag="img"
ref={ref}
alt=""
className="size-12 flex-none rounded-sm bg-surface-sunken object-cover"
/>
);
}

View File

@ -0,0 +1,3 @@
export { FileField } from './FileField';
export type { FileFieldLabels, FileFieldProps } from './types';
export { fileDropVariants, filePickedVariants } from './variants';

View File

@ -0,0 +1,36 @@
import type { ReactNode } from 'react';
/** Every text the field shows, from the translations. */
export type FileFieldLabels = {
/** «انتخاب فایل». */
pick: ReactNode;
/** The accepted types and size, under the pick text: «JPG یا PNG، حداکثر ۵ مگابایت». */
rules: ReactNode;
/** The remove button's accessible name: «حذف تصویر». */
remove: string;
/** While uploading, given the percent: «در حال بارگذاری… ۶۴٪». */
uploading?: (percent: number) => ReactNode;
};
export type FileFieldProps = {
label: ReactNode;
/** A rule given before picking: «یک تصویر واضح … آپلود کنید.». */
hint?: ReactNode;
file: File | null;
/** The picked file's size, formatted by the caller: «۱٫۸ مگابایت». */
size?: ReactNode;
/** A picked file, or `null` when removed. Check type and size here, when it is picked. */
onChange: (file: File | null) => void;
onBlur?: () => void;
/** MIME types for the picker, such as `image/jpeg,image/png`. */
accept?: string;
/** Inline error under the box; a rejected file leaves the box empty. */
error?: ReactNode;
/** 0–100 while the file uploads: the bar replaces the remove button. */
progress?: number;
disabled?: boolean;
labels: FileFieldLabels;
id?: string;
name?: string;
className?: string;
};

View File

@ -0,0 +1,28 @@
import { cva } from 'class-variance-authority';
/** The empty box: the whole box is the picker's label, so it is one large target. */
export const fileDropVariants = cva(
'min-h-30 rounded-md border border-dashed bg-surface-sunken px-4 py-5 text-center transition-colors duration-120 ease-standard has-focus-visible:focus-ring',
{
variants: {
invalid: {
true: 'border-danger',
false:
'border-border-default actionable:cursor-pointer hover:border-text-secondary',
},
disabled: { true: 'frozen', false: '' },
},
defaultVariants: { invalid: false, disabled: false },
},
);
/** The picked file's row: thumbnail, name and size, then remove or the upload bar. */
export const filePickedVariants = cva(
'min-h-18 rounded-md border bg-surface p-3',
{
variants: {
invalid: { true: 'border-danger', false: 'border-border-default' },
},
defaultVariants: { invalid: false },
},
);

View File

@ -18,6 +18,7 @@ export function Toast({
action,
announce = true,
children,
description,
className,
}: ToastProps) {
const role = tone === 'error' ? 'alert' : 'status';
@ -29,9 +30,16 @@ export function Toast({
className={cn(toastVariants(), className)}
>
{icon && <Icon name={icon} className={toastIconVariants({ tone })} />}
<Typography tag="span" color="inverse" className="min-w-0 flex-1">
{children}
</Typography>
<FlexBox direction="flex-col" gap="gap-1" className="min-w-0 flex-1">
<Typography tag="span" color="inverse">
{children}
</Typography>
{description != null && (
<Typography tag="span" variant="body-sm" color="inverse">
{description}
</Typography>
)}
</FlexBox>
{action && (
<Element
tag="button"

View File

@ -9,13 +9,14 @@ import type { ShowToastOptions } from './types';
* closes the toast. Returns the toast's id for `dismissToast`.
*/
export function showToast({
id,
message,
action,
duration,
...props
}: ShowToastOptions): string | number {
return toast.custom(
(id) => (
(toastId) => (
<Toast
{...props}
// The region already reads toasts politely; only an error keeps its own alert.
@ -24,7 +25,7 @@ export function showToast({
action && {
label: action.label,
onClick: () => {
toast.dismiss(id);
toast.dismiss(toastId);
action.onClick();
},
}
@ -34,6 +35,7 @@ export function showToast({
</Toast>
),
{
id,
duration:
duration ??
(action ? TOAST_WITH_ACTION_DURATION_MS : TOAST_DURATION_MS),

View File

@ -24,6 +24,8 @@ export type ToastProps = {
announce?: boolean;
/** One line, past tense, no exclamation mark: «اشتراک شما فعال شد.» */
children: ReactNode;
/** A second line under it: a failed action's reason and what to do, or the reference code. */
description?: ReactNode;
className?: string;
};
@ -32,6 +34,8 @@ export type ShowToastOptions = Omit<
'announce' | 'children' | 'className'
> & {
message: ReactNode;
/** A toast shown again under the same id replaces the old one instead of stacking. */
id?: string;
/** Defaults to 4 seconds, 6 with an action. */
duration?: number;
};

View File

@ -1,5 +1,6 @@
import { SkeletonRegion } from '../../atoms/skeleton';
import { FigureSkeleton } from './components/FigureSkeleton';
import { FormSkeleton } from './components/FormSkeleton';
import { HeaderSkeleton } from './components/HeaderSkeleton';
import { ListSkeleton } from './components/ListSkeleton';
import { PostSkeleton } from './components/PostSkeleton';
@ -44,6 +45,7 @@ export function SkeletonPreset({
{preset === 'figure' && <FigureSkeleton />}
{preset === 'list' && <ListSkeleton rows={n} avatar={avatar} />}
{preset === 'table' && <TableSkeleton rows={n} columns={columns} />}
{preset === 'form' && <FormSkeleton fields={n} />}
</SkeletonRegion>
);
}

View File

@ -0,0 +1,31 @@
import { FlexBox } from '../../../atoms/flex-box';
import { Skeleton } from '../../../atoms/skeleton';
import type { FormSkeletonProps } from '../types';
/**
* A form step: the heading and its one-line description, n labelled fields, the full-width submit
* button and the switch link under it. No card: it fills whatever frame the screen draws.
*/
export function FormSkeleton({ fields }: FormSkeletonProps) {
return (
<FlexBox direction="flex-col" gap="gap-5" aria-hidden>
<FlexBox direction="flex-col" gap="gap-2">
<Skeleton className="h-6 w-[55%]" />
<Skeleton className="w-[75%]" />
</FlexBox>
{Array.from({ length: fields }, (_, field) => (
<FlexBox
// Static placeholders that never reorder, so the index is a stable key.
key={field}
direction="flex-col"
gap="gap-2"
>
<Skeleton className="w-24" />
<Skeleton shape="rect" className="h-input-height w-full" />
</FlexBox>
))}
<Skeleton shape="pill" className="h-control-lg w-full" />
<Skeleton className="mx-auto w-40" />
</FlexBox>
);
}

View File

@ -9,6 +9,7 @@ export const PRESET_REPEATS: Partial<
prediction: { initial: 1, max: 3 },
list: { initial: 4, max: 4 },
table: { initial: 5, max: 5 },
form: { initial: 1, max: 6 },
};
export const DEFAULT_TABLE_COLUMNS = 5;

View File

@ -17,14 +17,17 @@ export type SkeletonPresetName =
/** Admin tables, with a sunken header row. */
| 'table'
/** A money hero («قابل واریز») with two tiles under it. */
| 'figure';
| 'figure'
/** A form step: heading, description, `count` fields, the submit button and a link. */
| 'form';
export type SkeletonPresetProps = {
/** The component the screen is waiting for. */
preset: SkeletonPresetName;
/**
* Repeats, capped at one screen: posts and predictions (default 1, at most 3), list rows
* (default 4, at most 4), table rows (default 5, at most 5). Other presets ignore it.
* (default 4, at most 4), table rows (default 5, at most 5), form fields (default 1, at most 6).
* Other presets ignore it.
*/
count?: number;
/** `table` only (default 5). */
@ -52,6 +55,10 @@ export type ListSkeletonProps = {
avatar: boolean;
};
export type FormSkeletonProps = {
fields: number;
};
export type TableSkeletonProps = {
rows: number;
columns: number;