@dloizides/ui-card-roster 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: `CardRoster` (groups, live card band, Reorder mode, ModalShell edit
+  sheet / wide split pane, uploading + upload-error + empty-group states), pure roster
+  helpers, `useRosterEditor`, `useRosterActions`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @dloizides/ui-card-roster
+
+A generic grouped card roster editor for React Native / RN-web. The host supplies the
+card body and the edit form as render props and every string as a prop; the package
+owns the groups, the card band, Reorder mode, the edit sheet and the upload/empty states.
+
+- **Groups**: add (`createGroup`), inline rename, remove (default: only when empty).
+- **Live band**: a horizontal row of framed cards per group, each with an Edit button.
+- **Reorder mode**: a separate mode with up/down buttons for cards and groups
+  (keyboard/switch reachable), animated with `@dloizides/ui-motion` `Reorder`.
+- **Edit sheet slot**: `@dloizides/ui-layout` `ModalShell` below `wideBreakpoint`
+  (default `LAYOUT_COLLAPSE_BREAKPOINT`, 768); a split pane at/above it.
+- **States**: per-item `busy` (uploading overlay) and `error` (+ retry) via
+  `getItemState`; empty-group message; roster-level `error` via ui-feedback `ErrorState`.
+- 44x44 minimum hit box on every control; colours from the ui-feedback `UiProvider` theme.
+
+```tsx
+<CardRoster
+  value={value}                       // { groups: [{ key, title, items: [{ id, ... }] }] }
+  onChange={setValue}
+  getItemName={(p) => p.name}
+  renderCard={(p) => <PersonCard person={p} />}
+  renderEditor={({ item, save, cancel, remove, isNew }) => <PersonForm ... />}
+  createItem={(groupKey) => ({ id: newId(), name: '' })}
+  createGroup={() => ({ key: newId(), title: FM('people.newGroup'), items: [] })}
+  getItemState={(p) => uploads[p.id]}
+  labels={labels}                     // CardRosterLabels — translated by the host
+/>
+```
+
+Pure helpers (`addGroup`, `renameGroup`, `removeGroup`, `moveGroup`, `addItem`,
+`updateItem`, `removeItem`, `moveItem`, `findItem`, `moveInArray`, `canMove`) return the
+same reference on a no-op. Peer deps: `@dloizides/ui-feedback`, `@dloizides/ui-layout`,
+`react`, `react-native`.

package/dist/index.d.mts

@@ -0,0 +1,208 @@
+import React from 'react';
+
+/** Anything with a stable id can live in a roster. */
+interface RosterItem {
+    id: string;
+}
+/** One titled group of cards, e.g. a section of a list. */
+interface RosterGroup<T extends RosterItem> {
+    key: string;
+    title: string;
+    items: T[];
+}
+/** The whole controlled value of a `<CardRoster>`. */
+interface RosterValue<T extends RosterItem> {
+    groups: RosterGroup<T>[];
+}
+/** Transient per-item state the HOST owns (an upload in flight, an upload that failed). */
+interface RosterItemState {
+    busy?: boolean;
+    error?: string;
+}
+/** What the edit-sheet render prop receives. */
+interface RosterEditorContext<T extends RosterItem> {
+    item: T;
+    groupKey: string;
+    /** `true` when the item came from `createItem` and is not in the value yet. */
+    isNew: boolean;
+    /** Writes the item into the value (add or update) and closes the editor. */
+    save: (item: T) => void;
+    cancel: () => void;
+    /** Removes an existing item (no-op for a new one) and closes the editor. */
+    remove: () => void;
+}
+/**
+ * Every visible string and accessibility text. The package ships NO copy: the host
+ * passes translated strings. Functions receive the item/group name for a11y labels.
+ */
+interface CardRosterLabels {
+    edit: string;
+    add: string;
+    rename: string;
+    remove: string;
+    reorder: string;
+    reorderHint: string;
+    doneReordering: string;
+    doneReorderingHint: string;
+    addGroup: string;
+    addGroupHint: string;
+    renameGroup: (title: string) => string;
+    renameGroupHint: string;
+    groupTitleInput: string;
+    groupTitleInputHint: string;
+    removeGroup: (title: string) => string;
+    removeGroupHint: string;
+    moveGroupUp: (title: string) => string;
+    moveGroupDown: (title: string) => string;
+    moveGroupHint: string;
+    addCard: (groupTitle: string) => string;
+    addCardHint: string;
+    editCard: (name: string) => string;
+    editCardHint: string;
+    moveCardUp: (name: string) => string;
+    moveCardDown: (name: string) => string;
+    moveCardHint: string;
+    emptyGroup: string;
+    editorTitleNew: string;
+    editorTitleEdit: string;
+    selectPrompt: string;
+    uploading: string;
+    retry: string;
+    retryHint: string;
+}
+/** A roster-level failure (e.g. the last save or upload failed). */
+interface CardRosterError {
+    message: string;
+    title?: string;
+    onRetry?: () => void;
+}
+interface CardRosterProps<T extends RosterItem> {
+    value: RosterValue<T>;
+    onChange: (next: RosterValue<T>) => void;
+    /** The card body. The roster draws the frame, the edit button and the states. */
+    renderCard: (item: T, group: RosterGroup<T>) => React.ReactNode;
+    /** The edit form, shown in a sheet (narrow) or the right pane (wide). */
+    renderEditor: (context: RosterEditorContext<T>) => React.ReactNode;
+    /** Human name of an item, used in accessibility labels. */
+    getItemName: (item: T) => string;
+    labels: CardRosterLabels;
+    /** Enables the per-group Add button; returns a fresh unsaved item. */
+    createItem?: (groupKey: string) => T;
+    /** Enables the Add group button; returns a fresh group (host owns key generation). */
+    createGroup?: () => RosterGroup<T>;
+    /** Default: only an EMPTY group can be removed, so removal never drops cards. */
+    canRemoveGroup?: (group: RosterGroup<T>) => boolean;
+    getItemState?: (item: T) => RosterItemState | undefined;
+    onRetryItem?: (item: T) => void;
+    error?: CardRosterError;
+    /** Width at/above which the editor becomes a split pane. Default: ui-layout's breakpoint. */
+    wideBreakpoint?: number;
+    cardWidth?: number;
+    testID?: string;
+}
+
+/**
+ * CardRoster — a generic grouped card editor. Composed narrow-first: one column with the
+ * edit form in a sheet; at/above `wideBreakpoint` the form moves into a right-hand pane.
+ * The value is controlled; every edit is a pure helper from `utils/rosterOps`.
+ */
+
+declare function CardRoster<T extends RosterItem>(props: CardRosterProps<T>): React.ReactElement;
+
+/**
+ * Pure, immutable reducer helpers over a `RosterValue`. Every helper returns the SAME
+ * reference when the operation is a no-op (unknown key, out-of-range move, duplicate
+ * id), so callers can skip `onChange` with a reference check.
+ */
+
+interface FoundItem<T extends RosterItem> {
+    group: RosterGroup<T>;
+    item: T;
+    index: number;
+}
+/** `true` when moving `index` by `delta` stays inside a list of `length`. */
+declare function canMove(length: number, index: number, delta: number): boolean;
+/** Moves one element; returns `list` itself when the move is out of range. */
+declare function moveInArray<X>(list: X[], index: number, delta: number): X[];
+declare function isGroupEmpty<T extends RosterItem>(group: RosterGroup<T>): boolean;
+declare function findItem<T extends RosterItem>(value: RosterValue<T>, itemId: string): FoundItem<T> | undefined;
+declare function addGroup<T extends RosterItem>(value: RosterValue<T>, group: RosterGroup<T>): RosterValue<T>;
+/** Trims the title; an empty or unchanged title is a no-op. */
+declare function renameGroup<T extends RosterItem>(value: RosterValue<T>, key: string, title: string): RosterValue<T>;
+declare function removeGroup<T extends RosterItem>(value: RosterValue<T>, key: string): RosterValue<T>;
+declare function moveGroup<T extends RosterItem>(value: RosterValue<T>, key: string, delta: number): RosterValue<T>;
+/** Appends to the group; refuses an id already present anywhere in the roster. */
+declare function addItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, item: T): RosterValue<T>;
+declare function updateItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, item: T): RosterValue<T>;
+declare function removeItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, itemId: string): RosterValue<T>;
+declare function moveItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, itemId: string, delta: number): RosterValue<T>;
+
+/**
+ * Pure edit-session logic: which item the editor shows, and how a save lands.
+ * Kept out of the hook so the rules are unit-tested without React.
+ */
+
+/** What the user opened: an existing item (`itemId`) or a new one (`itemId: null`). */
+interface EditTarget {
+    groupKey: string;
+    itemId: string | null;
+}
+interface EditSession<T extends RosterItem> {
+    item: T;
+    groupKey: string;
+    isNew: boolean;
+}
+/** `true` at/above the breakpoint: the editor renders as a split pane, not a sheet. */
+declare function isSplitPane(width: number, breakpoint: number): boolean;
+/**
+ * Resolves the target against the CURRENT value. An existing item that has since
+ * disappeared (removed elsewhere) resolves to `null`, which closes the editor; an
+ * item moved to another group resolves to its new group.
+ */
+declare function resolveEditSession<T extends RosterItem>(value: RosterValue<T>, target: EditTarget | null, draft: T | null): EditSession<T> | null;
+/** Applies a save: a new item is appended, an existing one replaced in place. */
+declare function commitEdit<T extends RosterItem>(value: RosterValue<T>, session: EditSession<T>, next: T): RosterValue<T>;
+
+interface UseRosterEditorResult<T extends RosterItem> {
+    /** `null` when the editor is closed. */
+    context: RosterEditorContext<T> | null;
+    /** Id of the existing item being edited (for the active-card highlight). */
+    activeItemId: string | null;
+    openEdit: (groupKey: string, itemId: string) => void;
+    openNew: (groupKey: string) => void;
+    close: () => void;
+}
+/** Owns the edit target + the unsaved draft of a new item; writes through `onChange`. */
+declare function useRosterEditor<T extends RosterItem>(value: RosterValue<T>, onChange: (next: RosterValue<T>) => void, createItem?: (groupKey: string) => T): UseRosterEditorResult<T>;
+
+interface RosterActions<T extends RosterItem> {
+    addGroup: (group: RosterGroup<T>) => void;
+    renameGroup: (key: string, title: string) => void;
+    removeGroup: (key: string) => void;
+    moveGroup: (key: string, delta: number) => void;
+    moveItem: (groupKey: string, itemId: string, delta: number) => void;
+}
+/** Binds the pure helpers to the controlled value; a no-op never calls `onChange`. */
+declare function useRosterActions<T extends RosterItem>(value: RosterValue<T>, onChange: (next: RosterValue<T>) => void): RosterActions<T>;
+
+/** Minimum hit box (CSS px) for every interactive element — mobile-first standard. */
+declare const MIN_TOUCH_TARGET = 44;
+declare const DEFAULT_CARD_WIDTH = 168;
+/** Move deltas for the reorder helpers. */
+declare const MOVE_UP = -1;
+declare const MOVE_DOWN = 1;
+declare const DEFAULT_TEST_ID = "card-roster";
+/** Stable testIDs derived from the roster's root testID. */
+declare const rosterTestIds: (base: string) => {
+    root: string;
+    reorderToggle: string;
+    addGroup: string;
+    error: string;
+    editor: string;
+    editorPlaceholder: string;
+    group: (key: string) => string;
+    card: (id: string) => string;
+};
+type RosterTestIds = ReturnType<typeof rosterTestIds>;
+
+export { CardRoster, type CardRosterError, type CardRosterLabels, type CardRosterProps, DEFAULT_CARD_WIDTH, DEFAULT_TEST_ID, type EditSession, type EditTarget, type FoundItem, MIN_TOUCH_TARGET, MOVE_DOWN, MOVE_UP, type RosterActions, type RosterEditorContext, type RosterGroup, type RosterItem, type RosterItemState, type RosterTestIds, type RosterValue, type UseRosterEditorResult, addGroup, addItem, canMove, commitEdit, findItem, isGroupEmpty, isSplitPane, moveGroup, moveInArray, moveItem, removeGroup, removeItem, renameGroup, resolveEditSession, rosterTestIds, updateItem, useRosterActions, useRosterEditor };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import React from 'react';
+
+/** Anything with a stable id can live in a roster. */
+interface RosterItem {
+    id: string;
+}
+/** One titled group of cards, e.g. a section of a list. */
+interface RosterGroup<T extends RosterItem> {
+    key: string;
+    title: string;
+    items: T[];
+}
+/** The whole controlled value of a `<CardRoster>`. */
+interface RosterValue<T extends RosterItem> {
+    groups: RosterGroup<T>[];
+}
+/** Transient per-item state the HOST owns (an upload in flight, an upload that failed). */
+interface RosterItemState {
+    busy?: boolean;
+    error?: string;
+}
+/** What the edit-sheet render prop receives. */
+interface RosterEditorContext<T extends RosterItem> {
+    item: T;
+    groupKey: string;
+    /** `true` when the item came from `createItem` and is not in the value yet. */
+    isNew: boolean;
+    /** Writes the item into the value (add or update) and closes the editor. */
+    save: (item: T) => void;
+    cancel: () => void;
+    /** Removes an existing item (no-op for a new one) and closes the editor. */
+    remove: () => void;
+}
+/**
+ * Every visible string and accessibility text. The package ships NO copy: the host
+ * passes translated strings. Functions receive the item/group name for a11y labels.
+ */
+interface CardRosterLabels {
+    edit: string;
+    add: string;
+    rename: string;
+    remove: string;
+    reorder: string;
+    reorderHint: string;
+    doneReordering: string;
+    doneReorderingHint: string;
+    addGroup: string;
+    addGroupHint: string;
+    renameGroup: (title: string) => string;
+    renameGroupHint: string;
+    groupTitleInput: string;
+    groupTitleInputHint: string;
+    removeGroup: (title: string) => string;
+    removeGroupHint: string;
+    moveGroupUp: (title: string) => string;
+    moveGroupDown: (title: string) => string;
+    moveGroupHint: string;
+    addCard: (groupTitle: string) => string;
+    addCardHint: string;
+    editCard: (name: string) => string;
+    editCardHint: string;
+    moveCardUp: (name: string) => string;
+    moveCardDown: (name: string) => string;
+    moveCardHint: string;
+    emptyGroup: string;
+    editorTitleNew: string;
+    editorTitleEdit: string;
+    selectPrompt: string;
+    uploading: string;
+    retry: string;
+    retryHint: string;
+}
+/** A roster-level failure (e.g. the last save or upload failed). */
+interface CardRosterError {
+    message: string;
+    title?: string;
+    onRetry?: () => void;
+}
+interface CardRosterProps<T extends RosterItem> {
+    value: RosterValue<T>;
+    onChange: (next: RosterValue<T>) => void;
+    /** The card body. The roster draws the frame, the edit button and the states. */
+    renderCard: (item: T, group: RosterGroup<T>) => React.ReactNode;
+    /** The edit form, shown in a sheet (narrow) or the right pane (wide). */
+    renderEditor: (context: RosterEditorContext<T>) => React.ReactNode;
+    /** Human name of an item, used in accessibility labels. */
+    getItemName: (item: T) => string;
+    labels: CardRosterLabels;
+    /** Enables the per-group Add button; returns a fresh unsaved item. */
+    createItem?: (groupKey: string) => T;
+    /** Enables the Add group button; returns a fresh group (host owns key generation). */
+    createGroup?: () => RosterGroup<T>;
+    /** Default: only an EMPTY group can be removed, so removal never drops cards. */
+    canRemoveGroup?: (group: RosterGroup<T>) => boolean;
+    getItemState?: (item: T) => RosterItemState | undefined;
+    onRetryItem?: (item: T) => void;
+    error?: CardRosterError;
+    /** Width at/above which the editor becomes a split pane. Default: ui-layout's breakpoint. */
+    wideBreakpoint?: number;
+    cardWidth?: number;
+    testID?: string;
+}
+
+/**
+ * CardRoster — a generic grouped card editor. Composed narrow-first: one column with the
+ * edit form in a sheet; at/above `wideBreakpoint` the form moves into a right-hand pane.
+ * The value is controlled; every edit is a pure helper from `utils/rosterOps`.
+ */
+
+declare function CardRoster<T extends RosterItem>(props: CardRosterProps<T>): React.ReactElement;
+
+/**
+ * Pure, immutable reducer helpers over a `RosterValue`. Every helper returns the SAME
+ * reference when the operation is a no-op (unknown key, out-of-range move, duplicate
+ * id), so callers can skip `onChange` with a reference check.
+ */
+
+interface FoundItem<T extends RosterItem> {
+    group: RosterGroup<T>;
+    item: T;
+    index: number;
+}
+/** `true` when moving `index` by `delta` stays inside a list of `length`. */
+declare function canMove(length: number, index: number, delta: number): boolean;
+/** Moves one element; returns `list` itself when the move is out of range. */
+declare function moveInArray<X>(list: X[], index: number, delta: number): X[];
+declare function isGroupEmpty<T extends RosterItem>(group: RosterGroup<T>): boolean;
+declare function findItem<T extends RosterItem>(value: RosterValue<T>, itemId: string): FoundItem<T> | undefined;
+declare function addGroup<T extends RosterItem>(value: RosterValue<T>, group: RosterGroup<T>): RosterValue<T>;
+/** Trims the title; an empty or unchanged title is a no-op. */
+declare function renameGroup<T extends RosterItem>(value: RosterValue<T>, key: string, title: string): RosterValue<T>;
+declare function removeGroup<T extends RosterItem>(value: RosterValue<T>, key: string): RosterValue<T>;
+declare function moveGroup<T extends RosterItem>(value: RosterValue<T>, key: string, delta: number): RosterValue<T>;
+/** Appends to the group; refuses an id already present anywhere in the roster. */
+declare function addItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, item: T): RosterValue<T>;
+declare function updateItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, item: T): RosterValue<T>;
+declare function removeItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, itemId: string): RosterValue<T>;
+declare function moveItem<T extends RosterItem>(value: RosterValue<T>, groupKey: string, itemId: string, delta: number): RosterValue<T>;
+
+/**
+ * Pure edit-session logic: which item the editor shows, and how a save lands.
+ * Kept out of the hook so the rules are unit-tested without React.
+ */
+
+/** What the user opened: an existing item (`itemId`) or a new one (`itemId: null`). */
+interface EditTarget {
+    groupKey: string;
+    itemId: string | null;
+}
+interface EditSession<T extends RosterItem> {
+    item: T;
+    groupKey: string;
+    isNew: boolean;
+}
+/** `true` at/above the breakpoint: the editor renders as a split pane, not a sheet. */
+declare function isSplitPane(width: number, breakpoint: number): boolean;
+/**
+ * Resolves the target against the CURRENT value. An existing item that has since
+ * disappeared (removed elsewhere) resolves to `null`, which closes the editor; an
+ * item moved to another group resolves to its new group.
+ */
+declare function resolveEditSession<T extends RosterItem>(value: RosterValue<T>, target: EditTarget | null, draft: T | null): EditSession<T> | null;
+/** Applies a save: a new item is appended, an existing one replaced in place. */
+declare function commitEdit<T extends RosterItem>(value: RosterValue<T>, session: EditSession<T>, next: T): RosterValue<T>;
+
+interface UseRosterEditorResult<T extends RosterItem> {
+    /** `null` when the editor is closed. */
+    context: RosterEditorContext<T> | null;
+    /** Id of the existing item being edited (for the active-card highlight). */
+    activeItemId: string | null;
+    openEdit: (groupKey: string, itemId: string) => void;
+    openNew: (groupKey: string) => void;
+    close: () => void;
+}
+/** Owns the edit target + the unsaved draft of a new item; writes through `onChange`. */
+declare function useRosterEditor<T extends RosterItem>(value: RosterValue<T>, onChange: (next: RosterValue<T>) => void, createItem?: (groupKey: string) => T): UseRosterEditorResult<T>;
+
+interface RosterActions<T extends RosterItem> {
+    addGroup: (group: RosterGroup<T>) => void;
+    renameGroup: (key: string, title: string) => void;
+    removeGroup: (key: string) => void;
+    moveGroup: (key: string, delta: number) => void;
+    moveItem: (groupKey: string, itemId: string, delta: number) => void;
+}
+/** Binds the pure helpers to the controlled value; a no-op never calls `onChange`. */
+declare function useRosterActions<T extends RosterItem>(value: RosterValue<T>, onChange: (next: RosterValue<T>) => void): RosterActions<T>;
+
+/** Minimum hit box (CSS px) for every interactive element — mobile-first standard. */
+declare const MIN_TOUCH_TARGET = 44;
+declare const DEFAULT_CARD_WIDTH = 168;
+/** Move deltas for the reorder helpers. */
+declare const MOVE_UP = -1;
+declare const MOVE_DOWN = 1;
+declare const DEFAULT_TEST_ID = "card-roster";
+/** Stable testIDs derived from the roster's root testID. */
+declare const rosterTestIds: (base: string) => {
+    root: string;
+    reorderToggle: string;
+    addGroup: string;
+    error: string;
+    editor: string;
+    editorPlaceholder: string;
+    group: (key: string) => string;
+    card: (id: string) => string;
+};
+type RosterTestIds = ReturnType<typeof rosterTestIds>;
+
+export { CardRoster, type CardRosterError, type CardRosterLabels, type CardRosterProps, DEFAULT_CARD_WIDTH, DEFAULT_TEST_ID, type EditSession, type EditTarget, type FoundItem, MIN_TOUCH_TARGET, MOVE_DOWN, MOVE_UP, type RosterActions, type RosterEditorContext, type RosterGroup, type RosterItem, type RosterItemState, type RosterTestIds, type RosterValue, type UseRosterEditorResult, addGroup, addItem, canMove, commitEdit, findItem, isGroupEmpty, isSplitPane, moveGroup, moveInArray, moveItem, removeGroup, removeItem, renameGroup, resolveEditSession, rosterTestIds, updateItem, useRosterActions, useRosterEditor };