@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/file-upload.d.ts

@@ -0,0 +1,152 @@
+import { type ReactNode } from 'react';
+/** One file the reader has chosen, and everything the list knows about it. */
+export type FileUploadFile = {
+    /**
+     * The caller's own identity for the file, and what the remove control reports.
+     *
+     * Required, and required as a string rather than as the name: a reader who adds
+     * the same file twice has two rows with the same name, and a remove control
+     * named by the file would announce two identical buttons.
+     */
+    id: string;
+    /** The file's name as the platform reported it. A word, so it is not truncated. */
+    name: string;
+    /**
+     * The file's size, in bytes.
+     *
+     * A number and not a formatted string, and the difference is the whole
+     * interface. A caller that hands over "1.2 MB" has done the division, picked a
+     * unit, decided the rounding and written a separator, and has to do all four
+     * again in every locale the product ships in, and again in every language. The
+     * number is a fact about the file and the sentence is Prism's to write.
+     */
+    size: number;
+    /**
+     * How far this file has got, out of a hundred.
+     *
+     * Omit it and the row shows no meter, which is right for a file that has
+     * finished and for a file that was never going to be uploaded. A value of zero
+     * is drawn as an empty meter rather than as nothing, because a transfer that
+     * has not started and a transfer that does not exist are different facts.
+     */
+    progress?: number;
+    /**
+     * What went wrong with this file, drawn under it in the destructive token and
+     * announced as it appears.
+     *
+     * A node, and a sentence about the caller's own limits: "Larger than 10 MB",
+     * "That file type is not accepted here". Prism does not decide what may be
+     * uploaded and does not write the sentence when it goes wrong.
+     */
+    error?: ReactNode;
+};
+/** The props the File upload accepts. */
+export interface FileUploadProps {
+    /**
+     * The files, in the order they were chosen.
+     *
+     * Required, and order is the caller's because it is a claim about importance.
+     * A reader who chose three files expects to see three rows in the order they
+     * arrived, not sorted by size.
+     */
+    files: FileUploadFile[];
+    /**
+     * Called with a file's `id` when the reader removes it.
+     *
+     * Omit it and the list is read-only, which is a legitimate state: a receipt
+     * names the files that were sent, and offering to take one off a receipt is a
+     * promise the caller cannot keep. A caller whose files are still uploading
+     * should omit it too, because this Component cannot see the transfer and will
+     * not try to stop one.
+     */
+    onRemove?: (id: string) => void;
+    /**
+     * The accessible name of one row's remove control, given that row's file name.
+     *
+     * Required whenever `onRemove` is given, and a function because the name has to
+     * name the file and the file's name is the caller's string, not this package's
+     * sentence. The Component throws without it rather than drawing a button it
+     * cannot name, because a nameless button is announced as "button" and the
+     * reader is left to work out which of the rows it belongs to.
+     */
+    removeLabel?: (name: string) => string;
+    /**
+     * The list's own name, drawn above it and used as its accessible name.
+     *
+     * A node and not a string, so the element a sighted reader reads is the one a
+     * screen reader names the list by. Without it the list is announced as an
+     * unlabelled list and the reader is told nothing about what the files are.
+     */
+    label?: ReactNode;
+    /**
+     * What to draw when no file has been chosen.
+     *
+     * An empty list with no `empty` renders nothing at all, which is the choice
+     * `FactList` makes and the reason is the same: a bordered box with a heading
+     * above it and nothing in it reads as a rendering failure rather than as an
+     * absence. Never a placeholder row. A row with no file in it is a row a reader
+     * tries to remove, and a row whose progress meter is at zero is a transfer that
+     * is happening.
+     */
+    empty?: ReactNode;
+    /**
+     * Renders a size in bytes as the sentence a reader sees.
+     *
+     * The default divides by 1024, steps up to kilobytes and then to megabytes,
+     * and asks `Intl` for the number and its unit in the runtime's own locale, so
+     * the grouping separators and the unit spelling are the reader's. A caller that
+     * needs a fixed locale, a different base or a fourth rung passes a function
+     * that closes over the locale it wants.
+     */
+    formatSize?: (bytes: number) => string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The list of files a reader has chosen, one row each.
+ *
+ * **A size is a number of bytes and never a formatted string.** That is the
+ * decision the whole interface rests on. A caller that formats the size itself
+ * has to reimplement the division, the unit ladder, the rounding at each rung and
+ * the grouping separator, and has to do it again for every locale the product
+ * ships in, and again the first time somebody asks for gigabytes. Prism owns one
+ * ladder and asks `Intl` for the sentence, so a locale change is a locale change
+ * and not an audit. The cost is that a caller who genuinely wants a different
+ * ladder writes a function, which is the right place for that decision.
+ *
+ * **The meter is `Progress` and the failure is `FieldError`, and they were not
+ * chosen together.** A bar that reports a position is a bar: `Progress` already
+ * exposes the value, the minimum and the maximum through ARIA, already draws at
+ * the authored heights and already animates the fill on the base duration, and a
+ * second meter written here would be a second answer to how far along a task is.
+ * The failure is the opposite case and deliberately is not an `Alert`. An Alert
+ * is a callout with its own border, its own padding and its own role, and one
+ * inside a bordered row is a card inside a card: it changes the height of the row
+ * that failed, it moves the remove control, and it announces a page-level problem
+ * for a problem with one file. `FieldError` is one line of destructive text with
+ * `role="alert"`, which is what a per-file failure is. The trade is that a reader
+ * gets no recovery beside the error, and the remedy for that is on the Dropzone
+ * beside the field, where the caller's own limits are stated.
+ *
+ * **The name is a word and the size is a number, and they are laid out that way
+ * on purpose.** The name takes what it needs and the size keeps its own width at
+ * the far edge, so a column of files reads as a column of names with a column of
+ * weights rather than as a ragged paragraph. The name truncates in the middle
+ * rather than at the end because a file extension is the part a reader recognises
+ * last, and a name cut before its extension is a name that could be anything.
+ *
+ * **An empty list renders `empty` or nothing, and never a placeholder row.** A
+ * row with no file in it is a row a reader will try to remove, and a row whose
+ * meter sits at zero is a transfer that is under way. The absence is either the
+ * caller's own sentence or no rows at all, which is what `FactList` does and for
+ * the same reason.
+ *
+ * It carries no directive. It holds no state: which files exist, how far each has
+ * got and which one is being removed are the caller's, and the meter it draws is
+ * a client Component that takes a number. A caller rendering a receipt from a
+ * server component gets a static list of what was sent, which is the right
+ * rendering of a receipt.
+ */
+declare function FileUpload({ files, onRemove, removeLabel, label, empty, formatSize, className, }: FileUploadProps): import("react").JSX.Element | null;
+export { FileUpload };
+//# sourceMappingURL=file-upload.d.ts.map

package/dist/components/ui/file-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../../../src/components/ui/file-upload.tsx"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAM7C,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,QAAQ,EACR,WAAW,EACX,KAAK,EACL,KAAK,EACL,UAA8B,EAC9B,SAAS,GACV,EAAE,eAAe,sCAoFjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/file-upload.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { XIcon } from 'lucide-react';
+import { useId } from 'react';
+import { FieldError } from './field.js';
+import { Progress } from './progress.js';
+import { cn } from '../../lib/utils.js';
+const KILOBYTE = 1024;
+const MEGABYTE = KILOBYTE * 1024;
+/**
+ * The default size sentence, in the runtime's locale.
+ *
+ * `Intl` is asked for the unit rather than for the abbreviation, because a unit
+ * has a localized spelling and an abbreviation does not: "kB" in one language is
+ * "Ko" in another and "KB" in a third, and hard-coding any of them ships one
+ * locale's abbreviation into every consumer's file list. The byte rung is first
+ * so that a four hundred byte file reads as four hundred bytes rather than as
+ * 0.4 of something, which is a number that looks like a measurement and is not
+ * one.
+ */
+const defaultFormatSize = (bytes) => {
+    const format = (unit, divisor) => new Intl.NumberFormat(undefined, {
+        style: 'unit',
+        unit,
+        maximumFractionDigits: divisor === 1 ? 0 : 1,
+    }).format(bytes / divisor);
+    if (bytes < KILOBYTE)
+        return format('byte', 1);
+    if (bytes < MEGABYTE)
+        return format('kilobyte', KILOBYTE);
+    return format('megabyte', MEGABYTE);
+};
+/**
+ * The remove control, drawn once and used by every row.
+ *
+ * The ink is the muted one and it is not themed per row, because every row is
+ * the same surface and a control that changed colour with the file's state would
+ * be a second thing to read. The target takes the 44px floor on a coarse pointer
+ * and the row grows to hold it, so a list of files on a phone is a list of rows
+ * a thumb can hit.
+ */
+const REMOVE_CONTROL = 'text-muted-foreground hover:text-foreground inline-flex size-5 shrink-0 items-center justify-center rounded-sm outline-none transition-colors duration-fast ease-out pointer-coarse:size-11 focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * The list of files a reader has chosen, one row each.
+ *
+ * **A size is a number of bytes and never a formatted string.** That is the
+ * decision the whole interface rests on. A caller that formats the size itself
+ * has to reimplement the division, the unit ladder, the rounding at each rung and
+ * the grouping separator, and has to do it again for every locale the product
+ * ships in, and again the first time somebody asks for gigabytes. Prism owns one
+ * ladder and asks `Intl` for the sentence, so a locale change is a locale change
+ * and not an audit. The cost is that a caller who genuinely wants a different
+ * ladder writes a function, which is the right place for that decision.
+ *
+ * **The meter is `Progress` and the failure is `FieldError`, and they were not
+ * chosen together.** A bar that reports a position is a bar: `Progress` already
+ * exposes the value, the minimum and the maximum through ARIA, already draws at
+ * the authored heights and already animates the fill on the base duration, and a
+ * second meter written here would be a second answer to how far along a task is.
+ * The failure is the opposite case and deliberately is not an `Alert`. An Alert
+ * is a callout with its own border, its own padding and its own role, and one
+ * inside a bordered row is a card inside a card: it changes the height of the row
+ * that failed, it moves the remove control, and it announces a page-level problem
+ * for a problem with one file. `FieldError` is one line of destructive text with
+ * `role="alert"`, which is what a per-file failure is. The trade is that a reader
+ * gets no recovery beside the error, and the remedy for that is on the Dropzone
+ * beside the field, where the caller's own limits are stated.
+ *
+ * **The name is a word and the size is a number, and they are laid out that way
+ * on purpose.** The name takes what it needs and the size keeps its own width at
+ * the far edge, so a column of files reads as a column of names with a column of
+ * weights rather than as a ragged paragraph. The name truncates in the middle
+ * rather than at the end because a file extension is the part a reader recognises
+ * last, and a name cut before its extension is a name that could be anything.
+ *
+ * **An empty list renders `empty` or nothing, and never a placeholder row.** A
+ * row with no file in it is a row a reader will try to remove, and a row whose
+ * meter sits at zero is a transfer that is under way. The absence is either the
+ * caller's own sentence or no rows at all, which is what `FactList` does and for
+ * the same reason.
+ *
+ * It carries no directive. It holds no state: which files exist, how far each has
+ * got and which one is being removed are the caller's, and the meter it draws is
+ * a client Component that takes a number. A caller rendering a receipt from a
+ * server component gets a static list of what was sent, which is the right
+ * rendering of a receipt.
+ */
+function FileUpload({ files, onRemove, removeLabel, label, empty, formatSize = defaultFormatSize, className, }) {
+    const generated = useId();
+    const labelId = `${generated}-label`;
+    if (onRemove !== undefined && removeLabel === undefined) {
+        throw new Error('FileUpload: a removable list needs removeLabel, because the accessible name of a remove control has ' +
+            'to name the file it removes and this Component cannot write that sentence. Pass a function of ' +
+            'the file name, or drop onRemove for a list the reader cannot change.');
+    }
+    if (files.length === 0 && empty === undefined)
+        return null;
+    return (_jsxs("div", { "data-slot": "file-upload", className: cn('flex w-full flex-col gap-1', className), children: [label === undefined ? null : (_jsx("span", { id: labelId, "data-slot": "file-upload-label", className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: label })), files.length === 0 ? (_jsx("p", { "data-slot": "file-upload-empty", className: "text-muted-foreground text-sm", children: empty })) : (_jsx("ul", { "data-slot": "file-upload-list", "aria-labelledby": label === undefined ? undefined : labelId, className: "flex w-full flex-col", children: files.map((file) => (_jsxs("li", { "data-slot": "file-upload-file", "data-incomplete": (file.error !== undefined ||
+                        (file.progress !== undefined && file.progress < 100)) ||
+                        undefined, className: "border-border flex items-start gap-3 border-b py-2 last:border-b-0", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { "data-slot": "file-upload-name", className: "min-w-0 truncate text-sm font-medium", children: file.name }), _jsx("span", { "data-slot": "file-upload-size", className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: formatSize(file.size) })] }), file.progress === undefined ? null : (_jsx(Progress, { value: file.progress, max: 100 })), file.error === undefined ? null : _jsx(FieldError, { children: file.error })] }), onRemove === undefined ? null : (_jsx("button", { type: "button", "data-slot": "file-upload-remove", "aria-label": removeLabel?.(file.name), onClick: () => onRemove(file.id), className: REMOVE_CONTROL, children: _jsx(XIcon, { className: "size-4", "aria-hidden": "true" }) }))] }, file.id))) }))] }));
+}
+export { FileUpload };

package/dist/components/ui/filter-panel.d.ts

@@ -0,0 +1,164 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** The props a `FilterPanelHeader` takes. */
+export interface FilterPanelHeaderProps extends Omit<ComponentProps<'div'>, 'title'> {
+    /**
+     * The id the panel's `aria-labelledby` points at.
+     *
+     * Supplied by `FilterPanel`, which generates it and puts it on the title
+     * element. A caller rendering a header inside their own `section` passes their
+     * own and sets `aria-labelledby` themselves, which is the arrangement the
+     * `title` prop exists to make unnecessary.
+     */
+    titleId: string;
+    /** The one line that names the panel. */
+    title?: ReactNode;
+    /**
+     * The caller's own account of what is currently applied.
+     *
+     * A node because the sentence is the consumer's: "3 filters" is true in one
+     * language and false in another, and so is "Showing archived runs". A panel
+     * that assembled the sentence would have assembled it in English, into a
+     * product that may not be in English.
+     */
+    summary?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/** The props a `FilterPanelFooter` takes. */
+export interface FilterPanelFooterProps extends ComponentProps<'div'> {
+    /**
+     * The apply and clear controls, as a slot.
+     *
+     * A slot and not a pair of props for two buttons, because the two are the
+     * consumer's decisions together: which one is primary, whether clear comes
+     * first, whether clear is even offered, and what each one says in the
+     * consumer's own words. A panel that drew them would be drawing all four.
+     */
+    children?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/** The props a `FilterPanel` takes. */
+export interface FilterPanelProps extends Omit<ComponentProps<'section'>, 'children' | 'title'> {
+    /**
+     * The one line that names the panel, and the accessible name of the region.
+     *
+     * A `ReactNode` rather than a string, because the panel's visible title is
+     * content. The accessible name is derived from this element by
+     * `aria-labelledby` rather than set separately, so the name a reader hears and
+     * the name a sighted reader reads are the same text by construction.
+     */
+    title?: ReactNode;
+    /**
+     * The caller's account of what is applied, shown in the header beside the
+     * title.
+     *
+     * In the header rather than the footer because it is a statement, not an
+     * instruction. A reader who has scrolled to the bottom of a tall filter column
+     * is looking for the button, and the statement about the state they are in has
+     * to be where they already were, at the top, or it is a thing they have to go
+     * looking for.
+     */
+    summary?: ReactNode;
+    /**
+     * The footer's slot, where apply and clear go.
+     *
+     * Rendered only when the caller passes it, because a footer band with nothing
+     * in it is a gap the reader looks through and a panel with no apply control is
+     * a panel whose filters apply themselves, which is the one thing this Component
+     * refuses to decide.
+     */
+    actions?: ReactNode;
+    /**
+     * The panel's accessible name, used only when there is no `title` to take it
+     * from.
+     *
+     * A `string` because this one is written into `aria-label`. With neither a
+     * title nor a name the region renders anonymous, which is the honest state
+     * rather than a name this package invented.
+     */
+    label?: string;
+    /** The filter controls, in the order a reader should meet them. */
+    children?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * A titled panel holding filter controls, with a summary above and a footer below.
+ *
+ * **The panel does not own apply and clear, and that is the whole reason it is a
+ * Component rather than a form.** The obvious version of this is a panel that
+ * applies on every change, and it is wrong for a reason that has nothing to do
+ * with performance: applying on change makes a decision about the consumer's data
+ * layer. It means a filter cannot be set before the next one is, that a request
+ * goes out per keystroke and per toggle, that the list behind the panel is
+ * rewritten while the reader is still choosing, and that a consumer with a large
+ * result set has to add debouncing to a Component they installed. The alternative
+ * is a panel that applies on a button, and that one has to know when the draft is
+ * complete: which filters are dependent on which others, whether a half-chosen
+ * range is valid, whether a pending change is a change. That is the consumer's
+ * fact about their own data, and it is not knowable from inside a layout panel.
+ * So the panel draws the frame, the summary slot and the footer slot, and the
+ * consumer supplies the two controls and owns every decision behind them. The
+ * cost is real and worth naming: a caller who wants the panel to own apply has to
+ * write four lines around it, and a caller who forgets gets filters that do
+ * nothing at all, which is a state the panel could have prevented by owning them
+ * and chose not to.
+ *
+ * **It is the same decision `list-panel` makes about its region, made once.**
+ * Both are a `section` named by its own title through `aria-labelledby`, both
+ * generate the title's id, and both fall back to `aria-label` only when the caller
+ * passes one and render anonymous otherwise. Two panels that named themselves
+ * differently would mean a reader meeting a named region in one place and an
+ * anonymous one in the next, from the same library, and the inconsistency would
+ * read as one of the two being wrong. So the rule is stated once here and
+ * `list-panel` states the same rule for its own frame: a `div` is not a landmark,
+ * a landmark a screen reader cannot name is a landmark they walk past twice, and
+ * a region Prism named for the caller is a claim about somebody else's product.
+ *
+ * **The summary is the caller's, and it is a slot rather than a count.** A panel
+ * that said "3 filters active" would be true in one language and false in another,
+ * and it would be wrong in this one the moment a filter has a range in it rather
+ * than a value. What is active is a fact about the consumer's state, and the
+ * sentence that states it is theirs.
+ *
+ * **The controls are the caller's own elements and the panel adds no wrapper per
+ * control.** A panel that wrapped each filter in its own row would assume the
+ * filters are single-line, which is false of a date range, a multi-select and
+ * anything with a hint under it. The panel is a column; the column's contents are
+ * the caller's, composed out of `Field`, `Checkbox`, `Switch` and `NativeSelect`,
+ * which is where the spacing and the naming of an individual control live.
+ *
+ * It is a server Component. It holds no state, reads no context and attaches no
+ * handler, so a filter column costs no JavaScript from this; the draft state, the
+ * apply handler and the clear handler are all the consumer's, which is the same
+ * argument as the rest of this Component's design and the reason the panel can be
+ * a plain `section` at all.
+ */
+declare function FilterPanel({ title, summary, actions, label, children, className, ...props }: FilterPanelProps): import("react").JSX.Element;
+/**
+ * The head of a filter panel: its title, and the caller's account of what is
+ * applied.
+ *
+ * Rendered by `FilterPanel` when either slot is present, and not at all when
+ * neither is, so a panel whose caller has not given it a title does not get a
+ * bordered band with nothing in it. The title element is a `span` carrying the
+ * id the panel points `aria-labelledby` at, rather than a heading: a filter
+ * column in a sidebar is not the heading of the region it sits in, and a heading
+ * here would put an entry in the page outline for a control cluster. A caller who
+ * wants a heading passes an element as `title` and keeps the name.
+ */
+declare function FilterPanelHeader({ titleId, title, summary, className, ...props }: FilterPanelHeaderProps): import("react").JSX.Element;
+/**
+ * The foot of a filter panel, where the apply and clear controls sit.
+ *
+ * On the muted surface and above a rule, for the reason a `ListPanel`'s footer is:
+ * it is the one band that does not scroll with the controls above it, and a
+ * reader who has set five filters has to be able to reach the control that commits
+ * them without scrolling back to a row they have already set. A caller who wants
+ * the pair in the other order, or a third control beside them, passes one slot and
+ * composes what it needs.
+ */
+declare function FilterPanelFooter({ className, ...props }: FilterPanelFooterProps): import("react").JSX.Element;
+export { FilterPanel, FilterPanelHeader, FilterPanelFooter };
+//# sourceMappingURL=filter-panel.d.ts.map

package/dist/components/ui/filter-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-panel.d.ts","sourceRoot":"","sources":["../../../src/components/ui/filter-panel.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE,6CAA6C;AAC7C,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAClF;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAuB,SAAQ,cAAc,CAAC,KAAK,CAAC;IACnE;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC7F;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,OAAO,EACP,OAAO,EACP,KAAK,EACL,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAoClB;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,iBAAiB,CAAC,EACzB,OAAO,EACP,KAAK,EACL,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE,sBAAsB,+BAmBxB;AAED;;;;;;;;;GASG;AACH,iBAAS,iBAAiB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,sBAAsB,+BAQzE;AAED,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/components/ui/filter-panel.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * A titled panel holding filter controls, with a summary above and a footer below.
+ *
+ * **The panel does not own apply and clear, and that is the whole reason it is a
+ * Component rather than a form.** The obvious version of this is a panel that
+ * applies on every change, and it is wrong for a reason that has nothing to do
+ * with performance: applying on change makes a decision about the consumer's data
+ * layer. It means a filter cannot be set before the next one is, that a request
+ * goes out per keystroke and per toggle, that the list behind the panel is
+ * rewritten while the reader is still choosing, and that a consumer with a large
+ * result set has to add debouncing to a Component they installed. The alternative
+ * is a panel that applies on a button, and that one has to know when the draft is
+ * complete: which filters are dependent on which others, whether a half-chosen
+ * range is valid, whether a pending change is a change. That is the consumer's
+ * fact about their own data, and it is not knowable from inside a layout panel.
+ * So the panel draws the frame, the summary slot and the footer slot, and the
+ * consumer supplies the two controls and owns every decision behind them. The
+ * cost is real and worth naming: a caller who wants the panel to own apply has to
+ * write four lines around it, and a caller who forgets gets filters that do
+ * nothing at all, which is a state the panel could have prevented by owning them
+ * and chose not to.
+ *
+ * **It is the same decision `list-panel` makes about its region, made once.**
+ * Both are a `section` named by its own title through `aria-labelledby`, both
+ * generate the title's id, and both fall back to `aria-label` only when the caller
+ * passes one and render anonymous otherwise. Two panels that named themselves
+ * differently would mean a reader meeting a named region in one place and an
+ * anonymous one in the next, from the same library, and the inconsistency would
+ * read as one of the two being wrong. So the rule is stated once here and
+ * `list-panel` states the same rule for its own frame: a `div` is not a landmark,
+ * a landmark a screen reader cannot name is a landmark they walk past twice, and
+ * a region Prism named for the caller is a claim about somebody else's product.
+ *
+ * **The summary is the caller's, and it is a slot rather than a count.** A panel
+ * that said "3 filters active" would be true in one language and false in another,
+ * and it would be wrong in this one the moment a filter has a range in it rather
+ * than a value. What is active is a fact about the consumer's state, and the
+ * sentence that states it is theirs.
+ *
+ * **The controls are the caller's own elements and the panel adds no wrapper per
+ * control.** A panel that wrapped each filter in its own row would assume the
+ * filters are single-line, which is false of a date range, a multi-select and
+ * anything with a hint under it. The panel is a column; the column's contents are
+ * the caller's, composed out of `Field`, `Checkbox`, `Switch` and `NativeSelect`,
+ * which is where the spacing and the naming of an individual control live.
+ *
+ * It is a server Component. It holds no state, reads no context and attaches no
+ * handler, so a filter column costs no JavaScript from this; the draft state, the
+ * apply handler and the clear handler are all the consumer's, which is the same
+ * argument as the rest of this Component's design and the reason the panel can be
+ * a plain `section` at all.
+ */
+function FilterPanel({ title, summary, actions, label, children, className, ...props }) {
+    const titleId = useId();
+    const named = title !== undefined;
+    const hasHeader = named || summary !== undefined;
+    const hasFooter = actions !== undefined && actions !== null && actions !== false;
+    return (_jsxs("section", { "data-slot": "filter-panel", "aria-labelledby": named ? titleId : undefined, "aria-label": named ? undefined : label, className: cn('bg-card text-card-foreground flex flex-col overflow-hidden rounded-lg border', className), ...props, children: [hasHeader ? (_jsx(FilterPanelHeader, { titleId: titleId, title: title, summary: summary })) : null, _jsx("div", { "data-slot": "filter-panel-body", className: "flex min-w-0 flex-1 flex-col p-4", children: children }), hasFooter ? _jsx(FilterPanelFooter, { children: actions }) : null] }));
+}
+/**
+ * The head of a filter panel: its title, and the caller's account of what is
+ * applied.
+ *
+ * Rendered by `FilterPanel` when either slot is present, and not at all when
+ * neither is, so a panel whose caller has not given it a title does not get a
+ * bordered band with nothing in it. The title element is a `span` carrying the
+ * id the panel points `aria-labelledby` at, rather than a heading: a filter
+ * column in a sidebar is not the heading of the region it sits in, and a heading
+ * here would put an entry in the page outline for a control cluster. A caller who
+ * wants a heading passes an element as `title` and keeps the name.
+ */
+function FilterPanelHeader({ titleId, title, summary, className, ...props }) {
+    return (_jsxs("div", { "data-slot": "filter-panel-header", className: cn('flex flex-col gap-1 border-b px-4 py-3', className), ...props, children: [title === undefined ? null : (_jsx("span", { id: titleId, "data-slot": "filter-panel-title", className: "text-sm font-medium", children: title })), summary === undefined ? null : (_jsx("span", { "data-slot": "filter-panel-summary", className: "text-muted-foreground text-xs", children: summary }))] }));
+}
+/**
+ * The foot of a filter panel, where the apply and clear controls sit.
+ *
+ * On the muted surface and above a rule, for the reason a `ListPanel`'s footer is:
+ * it is the one band that does not scroll with the controls above it, and a
+ * reader who has set five filters has to be able to reach the control that commits
+ * them without scrolling back to a row they have already set. A caller who wants
+ * the pair in the other order, or a third control beside them, passes one slot and
+ * composes what it needs.
+ */
+function FilterPanelFooter({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "filter-panel-footer", className: cn('bg-muted/50 flex items-center gap-3 border-t px-4 py-3', className), ...props }));
+}
+export { FilterPanel, FilterPanelHeader, FilterPanelFooter };