@apliteni/apliteni-ui 0.33.1 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -28,7 +28,7 @@ import '@apliteni/apliteni-ui/react/css';  // React components' shell styles (mo
 import { DataTable, Modal, Button } from '@apliteni/apliteni-ui/react';
 ```
 
-Components: `DataTable`, `Pagination`, `StatBand`, `Modal`, `Drawer`, `CommandPalette`, `Button`, `Badge`, `Card`, `Icon`.
+Components: `DataTable`, `Pagination`, `StatBand`, `Modal`, `Drawer`, `CommandPalette`, `Dropdown`, `BackLink`, `Button`, `Badge`, `Card`, `Icon`.
 
 `CommandPalette` renders the kit's `commandPalette()` markup, class for class, and imports the
 kit's ranking rather than repeating it — so a palette a server rendered and the same palette
@@ -94,6 +94,92 @@ closes both. The vanilla `drawer()`, `confirm()` and `commandPalette()` keep a s
 stack that this one cannot see, so do not open a React dialog and a vanilla overlay over
 each other on the same page.
 
+## Dropdown
+
+`Dropdown` renders the kit's `dropdown()` markup, class for class, and carries
+`wireDropdown()`'s keyboard: the arrows open it onto the first row or the selected one and
+then walk the ring, stepping over a disabled row and wrapping at both ends; Home and End go
+to the first and last; Enter and Space pick the row focus is on; Escape closes and returns
+focus to the trigger; Tab closes; a click outside closes it, and opening one closes every
+other on the page. Both flavours are here — `variant="select"` is a listbox that writes the
+pick into the trigger and moves the tick, `variant="menu"` is an action list — and, as in
+the factory, the variant is inferred when you leave it out.
+
+```tsx
+<Dropdown items={items} ariaLabel="Row actions" triggerContent="Actions"
+  onSelect={(value, item) => run(item)} />
+```
+
+**A row can be anything, including a router link.** `row` is handed the item and every prop
+the row has to carry — the classes, the role, the tab stop the panel moves itself, the pick
+and the click — and you spread them onto whatever element the row should be:
+
+```tsx
+import { Link } from 'react-router';
+
+<Dropdown items={items} row={(item, props) => <Link to={item.href!} {...props} />} />
+```
+
+That is the shape #304 was opened for, and it is a render prop rather than an `as` because
+the row is where a router link needs props of its own: `as={Link}` could pass the item's
+`href`, but not the `to`, `state`, `replace` or `prefetch` a real call site writes — and it
+could not vary them per row. Every row is still in the arrow-key ring, because the panel
+finds its rows by `data-dd-item`, which is in the props you spread.
+
+`open` and `onOpenChange` make the open state controlled, the way `sort` does on `DataTable`;
+leave `open` out and the component keeps its own, starting from `defaultOpen`. `onSelect`
+reports the item's `value` and the item. Pass `ariaLabel` to a `select` dropdown: a listbox
+needs a name, and axe says so — the same reason every vanilla dropdown story passes one.
+
+**`search` puts a field over the rows**, the same one the factory draws, and Guidelines /
+Component choice makes it a rule at ten options or any list fed by data:
+
+```tsx
+<Dropdown variant="select" label="currency:" ariaLabel="Currency" scroll={220}
+  search={{ placeholder: 'Search currencies' }} items={currencies} onSelect={setCurrency} />
+```
+
+Typing filters and focus stays in the field, which is a `role="combobox"` naming the row Enter
+would pick through `aria-activedescendant`. ↑ and ↓ walk the rows still showing, skip a disabled
+one and wrap; Enter picks; Home and End move the caret, because they belong to the text field;
+Escape closes and Tab closes. Every open starts from the whole list. A query that matches nothing
+shows "No match for “…”" and a nudge — reword either with `search.empty` (where `{q}` stands for
+the query) and `search.hint`. With a field in it the panel is a `role="dialog"`, so every row
+becomes an option: a row carrying `href` is drawn as a plain option rather than a link, exactly as
+the factory draws it — which is what `row` is for when the rows must be router links.
+
+**The match is the kit's, not this package's.** `dropdownMatch()` and `dropdownFiltering()` are
+exported from `@apliteni/apliteni-ui` and imported here, the way `CommandPalette` imports
+`rankGroups()`, so a list a server rendered and the same list after a keystroke hide the same
+rows. `Dropdown.test.tsx` types the same query into the factory-plus-`wireDropdown()` and into
+this component and compares what is left.
+
+Two things the factory has that this does not, both deliberate. It emits no `data-dropdown`
+on the container, so a page that calls `wireDropdown(document)` cannot adopt a dropdown React
+owns — the same decision `Drawer` makes about `data-drawer`; the row and panel hooks stay,
+because they are the row contract `docs/library.md` publishes. And it has no `portal: true`: the
+panel is a child of the trigger's container, so a dropdown inside `.ui-app__rail`
+(`position: sticky` with `overflow-y: auto`) still wants the vanilla factory.
+
+## BackLink
+
+`BackLink` is the kit's `backLink()`, rendered by React rather than through
+`dangerouslySetInnerHTML`. It holds the same rules: no address, or a `javascript:` one,
+renders nothing; the label is the destination as the sidebar spells it, and one that already
+says "Back to" is not said twice; the arrow is `aria-hidden`, so the accessible name says
+"Back to" that destination in words.
+
+```tsx
+<BackLink href="/invoices?status=open&page=3" label="Invoices" />
+<BackLink as={Link} to="/invoices" href="/invoices" label="Invoices" />
+```
+
+It renders the anchor itself, so `ui-back` is on the element the shell's
+`.ui-app__main > .ui-back` rule looks for — which is the whole reason a stateless component
+is here. `as` takes the element the link is drawn as and passes it every prop this component
+does not read, which is how a router link gets its own `to`; `href` is still required,
+because it is what the `javascript:` guard reads.
+
 ## Work on them
 
 From the repo root — one `npm install` covers the workspace:

package/react/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, ButtonHTMLAttributes } from 'react';
+import { ReactNode, ButtonHTMLAttributes, MouseEvent, ElementType, ComponentPropsWithoutRef } from 'react';
 
 declare function Icon({ name }: {
     name: string;
@@ -243,7 +243,127 @@ type DeniedProps = {
 };
 declare function Denied({ title, sub, need, icon, className, children, }: DeniedProps): react.JSX.Element;
 
+type DropdownBadge = string | {
+    text: string;
+    tone?: string;
+};
+type DropdownItem = {
+    label: string;
+    /** The pick, as `onSelect` reports it and as `data-value` carries it. */
+    value?: string | number;
+    description?: string;
+    /** A kit glyph name, drawn in the row's leading slot. */
+    icon?: string;
+    badge?: DropdownBadge;
+    selected?: boolean;
+    disabled?: boolean;
+    danger?: boolean;
+    /** A row that goes somewhere. A `select` row never becomes a link, as the factory decides it. */
+    href?: string;
+    target?: string;
+};
+/** A rule between rows. `'---'` is the factory's shorthand for the same thing. */
+type DropdownSeparator = '---' | {
+    separator: true;
+};
+type DropdownEntry = DropdownItem | DropdownSeparator;
+type DropdownSection = {
+    label?: string;
+    items?: DropdownEntry[];
+};
+/** The field above the rows. `true` takes every default. */
+type DropdownSearch = {
+    placeholder?: string;
+    /** Names the field. Without one it is named "Search " + the dropdown's name. */
+    label?: string;
+    /** The no-match line. `{q}` in it stands for the query. */
+    empty?: string;
+    /** The nudge under it. */
+    hint?: string;
+    /** What the field holds before it is opened; every open starts from the whole list. */
+    query?: string;
+};
+/**
+ * What a row has to carry to be a row: the classes, the role, the tab stop the
+ * panel moves itself, the pick and the click. Spread it onto whatever element the
+ * row should be — a router `<Link>`, a `<button>`, anything.
+ */
+type DropdownRowProps = {
+    className: string;
+    role: 'option' | 'menuitem';
+    tabIndex: -1;
+    'data-dd-item': string;
+    'data-value'?: string;
+    'aria-selected'?: boolean;
+    'aria-disabled'?: true;
+    href?: string;
+    target?: string;
+    /** Only with `search`: the field names the row Enter would pick. */
+    id?: string;
+    hidden?: boolean;
+    onClick: (e: MouseEvent) => void;
+    children: ReactNode;
+};
+type DropdownProps = {
+    /** Muted prefix in the trigger, e.g. "version:". */
+    label?: string;
+    /** What the trigger shows. Given one, the trigger is yours to update. */
+    value?: string;
+    placeholder?: string;
+    /** Inferred from the items when it is left out, exactly as the factory infers it. */
+    variant?: 'select' | 'menu';
+    items?: DropdownEntry[];
+    /** Grouped alternative to `items`. */
+    sections?: DropdownSection[];
+    header?: ReactNode;
+    footer?: ReactNode;
+    /** Replaces the trigger's label/value pair. With `ariaLabel`, names the trigger. */
+    triggerContent?: ReactNode;
+    triggerClass?: string;
+    chevron?: boolean;
+    /** The edge the panel hugs. */
+    align?: 'start' | 'end';
+    /** `'up'` opens into the space above the trigger. */
+    direction?: 'down' | 'up';
+    /** `true`, or a max height in px, to cap the panel and scroll it. */
+    scroll?: boolean | number;
+    /** A field above the rows that filters them as the reader types. */
+    search?: boolean | DropdownSearch;
+    ariaLabel?: string;
+    id?: string;
+    panelClass?: string;
+    /** Controlled: the host owns the open state and answers `onOpenChange`. */
+    open?: boolean;
+    /** Uncontrolled: where it starts. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    onSelect?: (value: string | number | undefined, item: DropdownItem) => void;
+    /** Draw the row yourself. `props` is everything the row needs; spread it. */
+    row?: (item: DropdownItem, props: DropdownRowProps) => ReactNode;
+};
+declare function Dropdown({ label, value, placeholder, variant, items, sections, header, footer, triggerContent, triggerClass, chevron, align, direction, scroll, search, ariaLabel, id, panelClass, open: openProp, defaultOpen, onOpenChange, onSelect, row, }: DropdownProps): react.JSX.Element;
+
+type BackLinkOwnProps = {
+    /** The address. No address, or a `javascript:` one, and nothing is rendered. */
+    href?: string;
+    /** The destination, spelled the way the sidebar or the trail spells it. */
+    label?: string;
+    className?: string;
+};
+type BackLinkProps<T extends ElementType = 'a'> = BackLinkOwnProps & {
+    /** The element the anchor is drawn as — a router `<Link>`, say. Default `'a'`. */
+    as?: T;
+} & Omit<ComponentPropsWithoutRef<T>, keyof BackLinkOwnProps | 'as'>;
+/**
+ * The link a page under another page puts above its title.
+ *
+ * The arrow says "back" on screen and is aria-hidden, so the link's accessible name
+ * says it in words: "Back to Invoices". Given `as`, the props this component does not
+ * read are passed through, which is how a router link gets its own `to`.
+ */
+declare function BackLink<T extends ElementType = 'a'>({ href, label, as, className, ...rest }: BackLinkProps<T>): react.JSX.Element | null;
+
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, Denied, type DeniedProps, Drawer, type DrawerProps, Icon, Modal, type ModalProps, PAGE_SIZES, Pagination, type PaginationProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, type TableSort, sortTableRows };
+export { BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, Denied, type DeniedProps, Drawer, type DrawerProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, Icon, Modal, type ModalProps, PAGE_SIZES, Pagination, type PaginationProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, type TableSort, sortTableRows };