@tristan2828/ui-foundation 4.12.0 → 4.13.0

package/conventions/docs/cell-patterns.md

@@ -934,15 +934,26 @@ row`), every editable cell is an editable value, exactly as on a view.
 one is open, "Saving…" and a refusal in the cell. There's no pencil
 column and no edit route.
 
-- **A cell** is `<EditableValue label="<Column> of <name>" layout="inline"
-  edit={editInPlace({ ... })}>`, its shown value the cell as it always
-  was. The label names the column and the row, so its pencil reads "Edit
-  Colour of Work" and its control "Colour of Work". The kinds are the
-  same: `text` (Enter saves), `choice` (the list opens with it, non-modal,
-  a pick saves), `multi`.
+- **A cell is one of the package's three row-edit cells**, or an
+  `<EditableValue label="<Column> of <name>" layout="inline"
+  edit={editInPlace({ ... })}>` for anything else. The label names the
+  column and the row, so its pencil reads "Edit Colour of Work" and its
+  control "Colour of Work".
+  - **`NameCell`**: one line; Enter saves, the form's rule (`schema`)
+    runs first, a taken name's 422 shows in the cell. `children` is how
+    the name shows at rest (an icon beside it).
+  - **`ChoiceCell<T>`** (`options`, `render`): the list opens with the
+    cell, non-modal; a pick saves, closing it with no pick gives up.
+    `render` draws a value at rest, on the trigger and in the list.
+  - **`LinkCell`** (`linkText`, `emptyLabel`, `save(link | null)`): a
+    link opening in a new tab (said to screen readers), or the not-set
+    label; edited as one line. A bare `example.com` gains `https://`,
+    another scheme (`javascript:`) is refused in the cell, and a blank
+    box saves `null`. Clicking the link follows it; the pencil edits.
 - **A cell is a component** (`<Entity><Field>Cell`) that calls
   `useEdit<Entity>Field(row.id)` for its save, the view's single-field
-  save. A hook can't be called inside a column definition.
+  save, and renders the package's cell with it. A hook can't be called
+  inside a column definition.
 - **Stable columns and row ids.** Make the column definitions once
   (at module level, or `useMemo`) and give
   `DataTable` a `getRowId`: new definitions every render, or rows keyed
@@ -958,24 +969,29 @@ column and no edit route.
   and its delete together on a wide screen.
 
 ```tsx
-// A cell is its own component, so it can call the record's save hook.
+import { ChoiceCell, InlineCreate, LinkCell, NameCell } from '@tristan2828/ui-foundation'
+
+// Each cell is its own component, so it can call the record's save hook.
 function CategoryColourCell({ category }: { category: Category }) {
   const editField = useEditCategoryField(category.id)       // optimistic: false, toastOnError: false
   return (
-    <EditableValue label={`Colour of ${category.name}`} layout="inline"
-      edit={editInPlace({
-        kind: 'choice',
-        value: category.colour,
-        schema: categoryFormSchema.shape.colour,
-        save: (colour) => editField.mutateAsync({ colour }),
-        control: (props) => (
-          <CategoryColourSelect id={props.id} value={props.value} onChange={(colour) => props.commit(colour)}
-            readOnly={props.disabled} defaultOpen modal={false} onOpenChange={(open) => !open && props.cancel()}
-            aria-label={props.label} aria-describedby={props.describedBy} />
-        ),
-      })}>
-      <ColourSwatch colour={category.colour} />
-    </EditableValue>
+    <ChoiceCell label={`Colour of ${category.name}`} value={category.colour} options={CATEGORY_COLOURS}
+      render={(colour) => <ColourSwatch colour={colour} />}
+      save={(colour) => editField.mutateAsync({ colour })} />
+  )
+}
+function CategoryNameCell({ category }: { category: Category }) {
+  const editField = useEditCategoryField(category.id)
+  return (
+    <NameCell label={`Name of ${category.name}`} value={category.name} schema={categoryFormSchema.shape.name}
+      save={(name) => editField.mutateAsync({ name })} />
+  )
+}
+function CategoryWebsiteCell({ category }: { category: Category }) {
+  const editField = useEditCategoryField(category.id)
+  return (
+    <LinkCell label={`Website of ${category.name}`} value={category.website} emptyLabel="No website"
+      save={(website) => editField.mutateAsync({ website })} />
   )
 }
 
@@ -983,6 +999,7 @@ function CategoryColourCell({ category }: { category: Category }) {
 const CATEGORY_COLUMNS: LegacyColumnDef<Category, unknown>[] = [
   { id: 'name', header: 'Name', cell: ({ row }) => <CategoryNameCell category={row.original} /> },
   { id: 'colour', header: 'Colour', cell: ({ row }) => <CategoryColourCell category={row.original} /> },
+  { id: 'website', header: 'Website', cell: ({ row }) => <CategoryWebsiteCell category={row.original} /> },
   { id: 'actions', header: () => <span className="sr-only">Actions</span>, cell: ({ row }) => <DeleteCategoryAction category={row.original} /> },
 ]
 

package/dist/components/app/row-edit-cells.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import { type EditInPlaceOptions } from './edit-in-place.js';
+type Schema<TValue> = EditInPlaceOptions<unknown, TValue>['schema'];
+export type NameCellProps = {
+    /** The cell's name, column and row: "Name of Home". */
+    label: string;
+    /** The saved name. */
+    value: string;
+    /** Saves the new name (already checked by `schema`). Rejects with the AppError. */
+    save: (name: string) => Promise<unknown>;
+    /** The form's rule for the name (`schema.shape.name`): checked before anything is sent. */
+    schema?: Schema<string>;
+    /** How the name shows at rest (an icon beside it). Defaults to the name. */
+    children?: ReactNode;
+    /** The input's width class. Defaults to `w-48`. */
+    inputClassName?: string;
+};
+/** A name in one line: Enter saves, the form's rule runs first, a taken name's 422 shows in the cell. */
+export declare function NameCell({ label, value, save, schema, children, inputClassName }: NameCellProps): import("react").JSX.Element;
+export type ChoiceCellProps<T extends string> = {
+    /** The cell's name, column and row: "Colour of Home". */
+    label: string;
+    /** The saved value. */
+    value: T;
+    /** Every value, in the order the list shows them. */
+    options: readonly T[];
+    /** How a value shows: at rest, on the open trigger and in the list (a swatch and its word). */
+    render: (value: T) => ReactNode;
+    /** Saves the picked value. Rejects with the AppError. */
+    save: (value: T) => Promise<unknown>;
+    /** The trigger's width class. Defaults to `w-40`. */
+    triggerClassName?: string;
+};
+/** A single choice: its list opens with the cell, a pick saves, closing it with no pick gives up. */
+export declare function ChoiceCell<T extends string>({ label, value, options, render, save, triggerClassName, }: ChoiceCellProps<T>): import("react").JSX.Element;
+export type LinkCellProps = {
+    /** The cell's name, column and row: "Website of Home". */
+    label: string;
+    /** The saved address, or null when there's none. */
+    value: string | null;
+    /** Saves the address, or null to clear it (the box left blank). Rejects with the AppError. */
+    save: (link: string | null) => Promise<unknown>;
+    /** The link's text at rest. Defaults to the address without its scheme. */
+    linkText?: string | ((href: string) => ReactNode);
+    /** What the cell says with no address. Defaults to "Not set". */
+    emptyLabel?: string;
+    /** The input's width class. Defaults to `w-64`. */
+    inputClassName?: string;
+};
+/** An optional link: shown as a link out (or the not-set label), edited as one line; blank clears it. */
+export declare function LinkCell({ label, value, save, linkText, emptyLabel, inputClassName }: LinkCellProps): import("react").JSX.Element;
+export {};

package/dist/components/app/row-edit-cells.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExternalLinkIcon } from 'lucide-react';
+import { Input } from '../ui/input.js';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select.js';
+import { linkHref } from '../../lib/link-href.js';
+import { editInPlace } from './edit-in-place.js';
+import { EditableValue } from './editable-value.js';
+/** A name in one line: Enter saves, the form's rule runs first, a taken name's 422 shows in the cell. */
+export function NameCell({ label, value, save, schema, children, inputClassName = 'w-48' }) {
+    return (_jsx(EditableValue, { label: label, layout: "inline", edit: editInPlace({
+            kind: 'text',
+            value,
+            schema,
+            save,
+            control: (props) => (_jsx(Input, { id: props.id, className: inputClassName, value: props.value, readOnly: props.disabled, "aria-invalid": props.invalid || undefined, "aria-label": props.label, "aria-describedby": props.describedBy, onChange: (event) => props.onChange(event.target.value) })),
+        }), children: children ?? value }));
+}
+/** A single choice: its list opens with the cell, a pick saves, closing it with no pick gives up. */
+export function ChoiceCell({ label, value, options, render, save, triggerClassName = 'w-40', }) {
+    return (_jsx(EditableValue, { label: label, layout: "inline", edit: editInPlace({
+            kind: 'choice',
+            value,
+            save,
+            control: (props) => (_jsxs(Select, { value: props.value, onValueChange: (next) => {
+                    if (next)
+                        props.commit(next);
+                }, disabled: props.disabled, defaultOpen: true, modal: false, onOpenChange: (open) => {
+                    if (!open)
+                        props.cancel();
+                }, children: [_jsx(SelectTrigger, { id: props.id, className: triggerClassName, "aria-invalid": props.invalid || undefined, "aria-label": props.label, "aria-describedby": props.describedBy, children: _jsx(SelectValue, { children: (shown) => render(shown) }) }), _jsx(SelectContent, { children: options.map((option) => (_jsx(SelectItem, { value: option, children: render(option) }, option))) })] })),
+        }), children: render(value) }));
+}
+// A web or email address (`example.com` gains https://), blank for none.
+// Another scheme (`javascript:`) is refused before anything is sent.
+const LINK_RULE = {
+    safeParse: (value) => {
+        const href = linkHref(String(value ?? ''));
+        if (href === '')
+            return { success: true, data: null };
+        if (href === null) {
+            return { success: false, error: { issues: [{ message: 'Use a web or email address' }] } };
+        }
+        return { success: true, data: href };
+    },
+};
+function shownLinkText(href, linkText) {
+    if (typeof linkText === 'function')
+        return linkText(href);
+    return linkText ?? href.replace(/^(https?:\/\/|mailto:)/i, '').replace(/\/$/, '');
+}
+/** An optional link: shown as a link out (or the not-set label), edited as one line; blank clears it. */
+export function LinkCell({ label, value, save, linkText, emptyLabel = 'Not set', inputClassName = 'w-64' }) {
+    // Only an address the editor would have saved is shown as a link: a
+    // stored `javascript:` reads as text, never as something to click.
+    const href = value ? linkHref(value) : null;
+    return (_jsx(EditableValue, { label: label, layout: "inline", edit: editInPlace({
+            kind: 'text',
+            value: value ?? '',
+            schema: LINK_RULE,
+            save,
+            control: (props) => (_jsx(Input, { id: props.id, type: "url", inputMode: "url", className: inputClassName, value: props.value, placeholder: "https://", readOnly: props.disabled, "aria-invalid": props.invalid || undefined, "aria-label": props.label, "aria-describedby": props.describedBy, onChange: (event) => props.onChange(event.target.value) })),
+        }), children: !value ? (_jsx("span", { className: "text-muted-foreground", children: emptyLabel })) : href ? (_jsxs("a", { href: href, target: "_blank", rel: "noreferrer", className: "rounded-sm text-link underline underline-offset-4 outline-none focus-visible:ring-3 focus-visible:ring-ring/50", children: [shownLinkText(href, linkText), _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })) : (value) }));
+}

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';
+export { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.js';
 export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';

package/dist/index.js

@@ -34,6 +34,7 @@ export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';
 export { formatPlainDate } from './lib/plain-date.js';
+export { ChoiceCell, LinkCell, NameCell, } from './components/app/row-edit-cells.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {