@crewlethq/ui 0.2.0 → 0.3.0

package/dist/Select/Select.d.ts

@@ -0,0 +1,138 @@
+import { type FocusEventHandler, type ReactNode, type SelectHTMLAttributes } from 'react';
+export type SelectValue = string | number;
+export type SelectSize = 'sm' | 'md';
+export type SelectAlign = 'left' | 'right';
+/**
+ * How wide the control is.
+ *
+ * `full` is a field on a form, which takes the line it is given. `auto` is a
+ * picker in a toolbar: it sizes to the answer it is showing, between a floor
+ * that keeps a row of them even and a cap that stops one long value pushing
+ * the rest of the bar off the screen. A filter row of full-width selects is
+ * one question per line, which is not what a filter bar is.
+ */
+export type SelectWidth = 'full' | 'auto';
+/**
+ * Which control this is.
+ *
+ * `listbox` IS THE HOUSE STYLE, and it is the default. Every dropdown in the
+ * product is this one: it takes the theme, the density, the tokens and the
+ * layer stack, so a list opened in a dark dialog is drawn by the design system
+ * rather than by the operating system, and the two do not sit beside each
+ * other looking like two products. It is also the only one that can do what
+ * several surfaces need at all: more than one choice, a search over dozens, a
+ * group heading, a second line of identity under an option.
+ *
+ * What it had to earn back, and now does, is everything a reader got free from
+ * the platform: type-ahead, Home and End, disabled rows stepped over, the
+ * highlight announced through `aria-activedescendant`, Tab closing the list
+ * and carrying on, and a stored value the options no longer offer kept rather
+ * than silently swapped. Those live in `useOptionKeys` and `useListbox`, so
+ * there is one keyboard for every list in the package.
+ *
+ * `native` is a real `<select>` in uilet's chrome, and it is drawn ONLY where
+ * a caller asks for it by name. The one thing it still has that this cannot
+ * is the phone's own full-screen picker and the platform's assistive
+ * behaviour in a web view, so a surface that is mostly used on a handset can
+ * opt into it deliberately. It takes one choice only.
+ */
+export type SelectMode = 'listbox' | 'native';
+export interface SelectOption {
+    value: SelectValue;
+    label: ReactNode;
+    /** A second line under the label: a handle, a path, what the choice means. */
+    description?: ReactNode;
+    disabled?: boolean;
+    /** Options sharing a group are listed under its name, in first-seen order. */
+    group?: string;
+    /**
+     * What type-ahead and the search match against, where the label is not a
+     * string. Without it a node label is matched by its value, which is a
+     * worse answer than no match at all when the two differ.
+     */
+    text?: string;
+}
+/**
+ * The form-control properties that reach whichever element this draws.
+ *
+ * The focus handlers are typed on `HTMLElement` rather than on
+ * `HTMLSelectElement`, because the element a caller's handler lands on depends
+ * on the mode: the listbox's trigger is a button and the native mode's is a
+ * `select`. A handler written for the wider type works in both.
+ */
+type NativePassthrough = Pick<SelectHTMLAttributes<HTMLSelectElement>, 'autoFocus' | 'name' | 'required' | 'aria-describedby'> & {
+    onBlur?: FocusEventHandler<HTMLElement> | undefined;
+    onFocus?: FocusEventHandler<HTMLElement> | undefined;
+};
+export interface SelectProps extends NativePassthrough {
+    id?: string;
+    /**
+     * Which control to draw. `listbox` by default, which is the house style; ask
+     * for `native` only with a reason, and say it at the call site. See
+     * [SelectMode].
+     */
+    mode?: SelectMode | undefined;
+    /**
+     * The chosen value. In `multiple` mode an array; a value the options do not
+     * offer is kept rather than dropped, because a reference to something since
+     * renamed has to stay visible until somebody removes it on purpose.
+     */
+    value: SelectValue | SelectValue[] | undefined;
+    onChange?: (value: SelectValue | SelectValue[], option: SelectOption) => void;
+    options: SelectOption[];
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+    menuClassName?: string;
+    size?: SelectSize;
+    /** How wide the control is. See [SelectWidth]. */
+    width?: SelectWidth;
+    align?: SelectAlign;
+    /**
+     * A filter that is ON. It takes the accent border and the accent INK, which
+     * is what "here, this is narrowing the list" means everywhere else; the fill
+     * it used to take put a value on a coloured ground at 3.58:1.
+     */
+    active?: boolean;
+    /** Marks the value as refused. Sets `aria-invalid`. */
+    error?: boolean;
+    ariaLabel?: string;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    /** Listbox mode only. A native select cannot hold several choices usefully. */
+    multiple?: boolean;
+    renderTrigger?: (option: SelectOption | null, ctx: {
+        open: boolean;
+    }) => ReactNode;
+    renderOption?: (option: SelectOption, ctx: {
+        active: boolean;
+        selected: boolean;
+    }) => ReactNode;
+    renderMultiLabel?: (selected: SelectOption[]) => ReactNode;
+    /** The line shown when a search matches nothing. */
+    emptyMessage?: string;
+}
+/**
+ * A picker over a known set of values.
+ *
+ * WHAT CHANGED. The listbox mode used to add its own `mousedown` listener to
+ * the document and swallow every press inside its panel so the popover around
+ * it would not close, which is the shape a component takes when it is not on
+ * a shared stack. It is a popup on the layer stack now, so a press on a
+ * dialog's veil closes the list and leaves the dialog, and Escape reaches the
+ * list first and stops there.
+ *
+ * The keyboard is the shared listbox model, so the arrows wrap, the highlight
+ * is clamped rather than reset as a search narrows, and nothing is taken
+ * while an input method is composing a word. What this adds on top is what
+ * the model cannot know: which options are DISABLED, so the arrows, Home and
+ * End step over them rather than parking the highlight on a row Enter will
+ * refuse.
+ *
+ * THE HIGHLIGHT IS ANNOUNCED. The list points at its active row with
+ * `aria-activedescendant` and every row carries an id, which is what a screen
+ * reader reads as the arrows move. Without it the reader heard the list open
+ * and then silence.
+ */
+export declare const Select: import("react").ForwardRefExoticComponent<SelectProps & import("react").RefAttributes<HTMLElement>>;
+export {};

package/dist/Select/index.d.ts

@@ -0,0 +1,3 @@
+import './Select.css';
+export { Select } from './Select.js';
+export type { SelectAlign, SelectMode, SelectOption, SelectProps, SelectSize, SelectValue, } from './Select.js';

package/dist/Select/index.js

@@ -0,0 +1,5 @@
+export { Select } from '../chunk-5IMACPJS.js';
+import '../chunk-GTOUGQQK.js';
+import '../chunk-7RPGY3JE.js';
+import '../chunk-ITHXJHBB.js';
+import '../chunk-ODEQTPFM.js';

package/dist/Select-2X77FSWR.css

@@ -0,0 +1,350 @@
+/*
+ * Select: one chrome over two controls, and the product's only dropdown.
+ *
+ * The native mode is a real `<select>` drawn transparent over this frame, so
+ * the platform keeps its own overlay, its own type-ahead and, on a phone, its
+ * own full-screen picker. The listbox mode is the hand-built panel, portalled
+ * into the nearest layer host and drawn with the shared listbox register, so
+ * a list of options looks the same wherever it is offered from.
+ *
+ * The boundary is --color-border-control, like every other control: the
+ * hairline measured 1.27:1 in light, which is a box a reader has to know is
+ * there already.
+ */
+
+.crewlet-select {
+  /*
+   * The toolbar picker's bounds. The floor keeps a row of filters even when
+   * one of them is showing "Any"; the cap stops a long value pushing the rest
+   * of the bar off the screen, and the label truncates instead.
+   */
+  --crewlet-select-auto-min-width: 132px;
+  --crewlet-select-auto-max-width: 220px;
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  width: 100%;
+  min-height: var(--size-control-md);
+  background-color: var(--color-surface-subtle);
+  border: 1px solid var(--color-border-control);
+  border-radius: var(--radius-md);
+  color: var(--color-text-primary);
+  /* The boundary is the only thing that moves. The ring is an outline, which
+     takes no transition, and nothing else here paints a shadow. */
+  transition: border-color var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-select--sm {
+  min-height: var(--size-control-sm);
+}
+
+/* A picker in a toolbar sizes to its answer. See [SelectWidth]. */
+.crewlet-select--auto {
+  width: auto;
+  min-width: var(--crewlet-select-auto-min-width);
+  max-width: var(--crewlet-select-auto-max-width);
+  flex: 0 1 auto;
+}
+
+.crewlet-select:hover {
+  border-color: var(--color-border-hover);
+}
+
+/*
+ * ONE RING, and the same one every field in this package draws: an outline
+ * over the boundary, inset so a scroller cannot clip it. See Input.css for
+ * why it is not the border plus --shadow-focus it used to be, and why an
+ * outline is the half that survives forced-colors mode.
+ *
+ * :focus-within is enough HERE, where the Input's own rule has to name its
+ * control: this frame holds the trigger and a chevron, and the chevron takes
+ * no focus. Anything focusable added beside the trigger would have to narrow
+ * this selector, or its ring would be drawn inside the field's.
+ *
+ * It is also why the trigger is asked nothing about :focus-visible. A native
+ * <select> matches that on a pointer press and a <button> does not, so
+ * keying the frame on it would ring one of Select's two modes on a click and
+ * leave the other bare.
+ */
+.crewlet-select:focus-within {
+  outline: 2px solid var(--color-focus);
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+/*
+ * A FILTER THAT IS ON. The accent border says where the reader is and the
+ * accent INK says what it is set to. It used to be the accent FILL with the
+ * value written on it, which measured 3.58:1 in dark: the one control on the
+ * page whose whole job is to say "this list is narrowed" was the hardest to
+ * read on it.
+ */
+.crewlet-select.is-active {
+  border-color: var(--color-brand-accent);
+  color: var(--color-brand-accent-ink);
+}
+
+.crewlet-select.is-active .crewlet-select__label,
+.crewlet-select.is-active .crewlet-select__native,
+.crewlet-select.is-active .crewlet-select__chevron {
+  color: var(--color-brand-accent-ink);
+}
+
+.crewlet-select.is-error {
+  border-color: var(--color-feedback-danger);
+}
+
+/* A refused picker keeps its colour while the reader is in it: the ring
+   covers the boundary, so a focus-coloured one would paint out the refusal.
+   See Input.css. */
+.crewlet-select.is-error:focus-within {
+  outline-color: var(--color-feedback-danger);
+}
+
+.crewlet-select.is-disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* ── The trigger, native and built ───────────────────────────────────── */
+
+/*
+ * The trigger IS the field: the value sits on one line inset by the same step
+ * a text box insets its own, and the box's height is what makes the row. It
+ * stretches to the frame so a press anywhere in the control opens the list.
+ */
+.crewlet-select__native,
+.crewlet-select__trigger {
+  appearance: none;
+  -webkit-appearance: none;
+  flex: 1;
+  min-width: 0;
+  display: inline-flex;
+  align-items: center;
+  align-self: stretch;
+  gap: var(--spacing-2);
+  background: transparent;
+  border: none;
+  outline: none;
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--font-size-compact);
+  color: inherit;
+  text-align: left;
+  padding: 0 var(--spacing-3);
+  /* Room for the chevron, which sits over the control rather than beside it:
+     its own inset twice over, plus the glyph. */
+  padding-right: var(--spacing-6);
+}
+
+.crewlet-select--sm .crewlet-select__native,
+.crewlet-select--sm .crewlet-select__trigger {
+  font-size: var(--font-size-xs);
+  padding: 0 var(--spacing-2);
+  padding-right: var(--spacing-6);
+}
+
+.crewlet-select__native:disabled,
+.crewlet-select__trigger:disabled {
+  cursor: not-allowed;
+}
+
+/*
+ * THE TRIGGER DRAWS NO RING OF ITS OWN. The frame around it is the field a
+ * reader sees, and it is already ringed by the rule above. The transparent
+ * outline that used to sit here was the frame's forced-colors stand-in put on
+ * the wrong element: with the frame drawing a real outline now, that one was
+ * a second system-coloured ring inside the first for the readers that mode
+ * exists for, and it sat two pixels further out than the frame's own.
+ */
+.crewlet-select__label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Nothing chosen: the tertiary step, which is measured, because it is the
+   example of what belongs here rather than decoration. */
+.crewlet-select__label.is-placeholder {
+  color: var(--color-text-tertiary);
+}
+
+/*
+ * The chevron is DECORATION and takes the decoration step. It says a second
+ * time what the control's own role, name and boundary already say, and a mark
+ * that repeats is a mark that must not compete with the value beside it.
+ *
+ * The selector names the ELEMENT as well as the class, which is what says
+ * this is the one exemption the decoration step has: an svg, never a word.
+ */
+svg.crewlet-select__chevron {
+  position: absolute;
+  right: var(--spacing-2);
+  pointer-events: none;
+  color: var(--color-text-muted);
+}
+
+/* ── The panel ───────────────────────────────────────────────────────── */
+
+.crewlet-select__menu {
+  /* Six rows and a scroll. A list that draws past the bottom of the dialog
+     it was opened in is a list whose last answers nobody finds. */
+  --crewlet-select-menu-max-height: 12rem;
+
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  max-height: var(--crewlet-select-menu-max-height);
+  /*
+   * THE PANEL IS THE PRODUCT'S SURFACE, on the panel hairline, at the panel
+   * corner. A list offered from a field is another panel over the one the
+   * field is in, not a heavier kind of thing: the elevated surface and the
+   * large shadow it used to lift with read as a dialog, over a form the
+   * reader has not left.
+   */
+  background: var(--color-surface-subtle);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-md);
+  overflow: hidden;
+  /*
+   * The popover band. A list portalled out of its form has to paint over the
+   * dialog it was opened inside, and the shared listbox model does not hand
+   * back the layer's own depth, so this is the token for the band rather than
+   * a number.
+   */
+  z-index: var(--z-index-popover);
+}
+
+/* Inside a layer host the panel is placed against the host's own box. */
+.crewlet-select__menu--in-host {
+  position: absolute;
+}
+
+.crewlet-select__list {
+  flex: 1;
+  min-height: 0;
+}
+
+.crewlet-select__group {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+
+.crewlet-select__option {
+  align-items: flex-start;
+}
+
+/*
+ * WHAT IS CHOSEN AND WHERE THE READER IS ARE TWO DIFFERENT FACTS, and this
+ * list draws them with two different marks: the chosen row carries the tick,
+ * in the accent ink, and the row the arrows or the pointer are on carries the
+ * hover tint. Drawn as one tint they collided on the commonest list there is,
+ * a filter whose current answer is also the row it opens on.
+ *
+ * The rules are scoped to the panel rather than written on the option class,
+ * because the shared listbox register paints [aria-selected] itself and the
+ * stylesheets are bundled in hash order: a rule of equal weight would win or
+ * lose by the name of a build artefact.
+ */
+.crewlet-select__menu .crewlet-listbox__option,
+.crewlet-select__menu .crewlet-listbox__option[aria-selected='true'] {
+  border-radius: var(--radius-xs);
+  background: transparent;
+  color: var(--color-text-primary);
+}
+
+.crewlet-select__menu .crewlet-listbox__option.is-highlight,
+.crewlet-select__menu .crewlet-listbox__option:hover {
+  background: var(--color-surface-hover);
+  color: var(--color-text-primary);
+}
+
+/*
+ * A row a caller draws itself (`renderOption`) has no tick column, so the
+ * choice is said in the weight as well. It is the one mark that costs the row
+ * nothing: a custom row with no tick and no tint said nothing at all.
+ */
+.crewlet-select__menu .crewlet-listbox__option.is-selected {
+  font-weight: var(--font-weight-medium);
+}
+
+.crewlet-select__menu .crewlet-listbox__option.is-disabled {
+  background: transparent;
+  color: var(--color-text-tertiary);
+  cursor: not-allowed;
+}
+
+.crewlet-select__option-tick {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  margin-top: 1px;
+  color: var(--color-brand-accent-ink);
+}
+
+.crewlet-select__option-body {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+
+.crewlet-select__option-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.crewlet-select__option-desc {
+  font-size: var(--font-size-2xs);
+  line-height: var(--font-line-height-normal);
+  color: var(--color-text-tertiary);
+}
+
+/* The second line stays the second line on the row the reader is on: it is
+   the same fact, and a description that changes colour with the highlight
+   reads as a different kind of thing under the pointer. */
+.crewlet-select__menu .crewlet-listbox__option.is-highlight .crewlet-select__option-desc {
+  color: var(--color-text-tertiary);
+}
+
+/* ── The search box ──────────────────────────────────────────────────── */
+
+.crewlet-select__search {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  padding: var(--spacing-2) var(--spacing-3);
+  border-bottom: 1px solid var(--color-border-default);
+  color: var(--color-text-tertiary);
+  flex: none;
+}
+
+.crewlet-select__search-input {
+  flex: 1;
+  min-width: 0;
+  background: transparent;
+  border: none;
+  outline: none;
+  font: inherit;
+  font-size: var(--font-size-compact);
+  color: var(--color-text-primary);
+}
+
+.crewlet-select__search-input::placeholder {
+  color: var(--color-text-tertiary);
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-select {
+    transition: none;
+  }
+}

package/dist/Shortcut/index.d.ts

@@ -0,0 +1,2 @@
+export { matchesShortcut, useShortcut } from './useShortcut.js';
+export type { ShortcutChord, ShortcutKey, ShortcutOptions } from './useShortcut.js';

package/dist/Shortcut/index.js

@@ -0,0 +1,4 @@
+export { matchesShortcut, useShortcut } from '../chunk-F6OE5FH3.js';
+import '../chunk-7RPGY3JE.js';
+import '../chunk-ITHXJHBB.js';
+import '../chunk-ODEQTPFM.js';

package/dist/Shortcut/useShortcut.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A keyboard shortcut that belongs to the PAGE.
+ *
+ * WHY IT IS NOT A `keydown` LISTENER. Four rules separate a shortcut that
+ * works from one that fires in the wrong place, and every one of them was a
+ * defect somewhere before it was a rule here:
+ *
+ * - NOT A PRESS SOMETHING ELSE HAS ALREADY HANDLED. A surface that closes on
+ *   its own chord calls `preventDefault`, and a second handler acting on the
+ *   same press undoes what the first one did.
+ * - NOT A PRESS AN INPUT METHOD IS COMPOSING. Somebody typing Japanese,
+ *   Chinese or Korean builds each word in a composition, whose Enter, Escape
+ *   and arrows still reach the page as key presses. See `isComposing`.
+ * - NOT WHILE A MODAL HOLDS THE KEYBOARD. `aria-modal` says the page behind a
+ *   dialog cannot be reached, and a page shortcut that fires through it breaks
+ *   that in the most expensive way available: search opened over a dialog can
+ *   navigate, the navigation unmounts the dialog, and a write whose outcome
+ *   nobody has seen goes with it.
+ * - NOT A BARE KEY WHILE SOMEBODY IS TYPING. A slash is a search shortcut on
+ *   an empty page and a character in a filter box. The set of what counts as
+ *   typing includes `select`, which the dashboard this is ported from left
+ *   out: a slash pressed on a focused native select opened search instead of
+ *   jumping to the option the reader was spelling.
+ */
+/**
+ * A press with modifiers. `mod` is the platform's command key: Command on an
+ * Apple keyboard, Control everywhere else, so one binding is right on both.
+ */
+export interface ShortcutChord {
+    /** The key as the browser reports it, compared without case for a letter. */
+    key: string;
+    mod?: boolean | undefined;
+    shift?: boolean | undefined;
+    alt?: boolean | undefined;
+}
+/** A bare key (`'/'`, `'?'`) or a chord. */
+export type ShortcutKey = string | ShortcutChord;
+/**
+ * Whether this press is one of these shortcuts.
+ *
+ * Exported because a surface sometimes has to answer the same question about
+ * a press it is handed rather than about one it subscribed to: a command
+ * palette closes on the chord that opened it, and two spellings of "is this
+ * that chord" is how the two come to disagree.
+ */
+export declare function matchesShortcut(event: KeyboardEvent, keys: readonly ShortcutKey[]): boolean;
+export interface ShortcutOptions {
+    /** The presses that fire it. */
+    keys: readonly ShortcutKey[];
+    /** What to do. The press is already claimed with `preventDefault` by then. */
+    onKey: (event: KeyboardEvent) => void;
+    /**
+     * `page` is a shortcut the page owns, silent while a modal is open.
+     *
+     * `any` is for a shortcut owned by a surface that is itself up, because a
+     * surface cannot use `page`: it IS the modal that would silence it. It is
+     * NOT a way out of the modal rule, and the caller owes the other half of
+     * it: pass `enabled: isTopmost` from that surface's own `useModalLayer`, so
+     * the chord belongs to whichever surface holds the keyboard. Bound without
+     * it, a palette's own chord closes the palette from beneath a dialog raised
+     * over it, and focus lands behind that dialog's veil.
+     */
+    scope?: 'page' | 'any' | undefined;
+    /** False to unbind it, for a shortcut that belongs to a state. */
+    enabled?: boolean | undefined;
+}
+/** Binds `keys` for as long as the component is mounted and `enabled`. */
+export declare function useShortcut({ keys, onKey, scope, enabled }: ShortcutOptions): void;