@photon-ai/pho-ui 4.12.0 → 4.13.0

package/dist/src/components/scope/scope.d.ts

@@ -0,0 +1,98 @@
+import { ComponentProps, Ref } from 'react';
+/**
+ * Scope — pick what something covers out of a catalog: the events a webhook
+ * destination receives, the permissions an app or key holds. A searchable,
+ * grouped checklist with a catch-all row; `collapsible` folds it to a
+ * two-line summary for a resource that already exists, opening on click.
+ */
+export interface ScopeItem {
+    /**
+     * What the selection holds — an event type, a permission id. It is also
+     * the row's name unless `label` says otherwise.
+     */
+    value: string;
+    /** The row's name, when it shouldn't be the value itself. */
+    label?: string;
+    /** One line on what it covers. Searched along with the name. */
+    description?: string;
+    /**
+     * The group it files under — the resource, the namespace. Groups keep
+     * the order they first appear in; items without one come first.
+     */
+    group?: string;
+}
+export interface ScopeAll {
+    /** The row's name — `All events`. */
+    label: string;
+    /** What choosing it means — `Every current and future event.` */
+    description?: string;
+    /**
+     * A wildcard the selection holds in place of the items — `*`. With it,
+     * the row stands for every item, now and later: choosing it sets the
+     * selection to `[value]`, and leaving it spells every item out by name so
+     * the reader prunes from there, never from nothing. Without it, the row
+     * selects every item listed.
+     */
+    value?: string;
+}
+export interface ScopeProps extends Omit<ComponentProps<"div">, "defaultValue" | "onChange" | "children"> {
+    /** The catalog — everything that can be picked, in display order. */
+    items: readonly ScopeItem[];
+    /** The selected values, controlled. */
+    value?: readonly string[];
+    /** The selected values at first, uncontrolled. */
+    defaultValue?: readonly string[];
+    /**
+     * Called with the next selection, in catalog order (values no longer in
+     * the catalog follow in the order they were held).
+     */
+    onValueChange?: (value: string[]) => void;
+    /** The catch-all row at the top. Leave it out for no such row. */
+    all?: ScopeAll;
+    /** The search field's placeholder, which also names it. @default "Search" */
+    placeholder?: string;
+    /**
+     * Fold to a two-line summary of the selection, opening to the full list
+     * on click — for a resource that already exists, where the scope is read
+     * far more often than it changes. The page saves the change (its "Save
+     * changes" below the card) and folds the list through `open`; the ✕ in
+     * the search row, or `Escape` on an empty search, drops the edit: the
+     * selection goes back to what it was when the list opened, and folds.
+     */
+    collapsible?: boolean;
+    /** Whether the collapsible list is open, controlled. */
+    open?: boolean;
+    /** Whether the collapsible list starts open. @default false */
+    defaultOpen?: boolean;
+    /** Called when the collapsible list opens or folds. */
+    onOpenChange?: (open: boolean) => void;
+    /** The catalog is on its way: bones in place of rows. */
+    loading?: boolean;
+    /**
+     * Read-only: the list can be searched but not changed, and a folded one
+     * stays folded. Held open by `open` (a save in flight), nothing in it
+     * changes the selection, the ✕ and Escape included.
+     */
+    disabled?: boolean;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * A searchable, grouped checklist for choosing what something covers.
+ *
+ * Every row is one line on a wide card — the name, then its description in
+ * a second column that opens whole on hover when it doesn't fit. Groups are
+ * thin tinted bands carrying a checkbox for the whole group (mixed when
+ * partly chosen). The search matches names, descriptions, and group names,
+ * word by word; while it holds a query the catch-all row steps aside and a
+ * group's checkbox covers the rows it shows.
+ *
+ * With `collapsible`, the card rests as a summary — whole groups by name,
+ * the rest by item, over a count — and opens in place, the search taking
+ * focus, when clicked; its ✕ drops the edit and folds it back, the page's
+ * own save below the card commits it. Values the catalog no longer offers keep a row
+ * under "No longer offered": they can be removed, never added in bulk.
+ */
+export declare function Scope({ items, value: valueProp, defaultValue, onValueChange, all, placeholder, collapsible, open: openProp, defaultOpen, onOpenChange, loading, disabled, className, ref, ...props }: ScopeProps): import("react").JSX.Element;
+export declare namespace Scope {
+    var displayName: string;
+}

package/dist/src/motion/index.d.ts

@@ -128,6 +128,58 @@ export declare function fadeThroughBlur(reduceMotion?: boolean | null): {
         readonly duration: 0;
     };
 };
+/**
+ * The presence recipe — `BasicPage.Reveal`'s: a block opens from no height
+ * on `SPRING_ENTRANCE` while `FADE_ENTRANCE` brings the ink, and closes the
+ * same way. Spread onto a keyed motion element inside `AnimatePresence`,
+ * clipped while it moves so what hasn't opened stays out of sight:
+ *
+ *     <motion.div {...revealIn(reduceMotion)} />
+ *
+ * `collapseGap` is a flex gap the block trades against its height (a
+ * negative margin as it closes), so neighbours glide to where they end up
+ * instead of snapping by the gap when it unmounts. Under reduced motion the
+ * block snaps.
+ */
+export declare function revealIn(reduceMotion?: boolean | null, collapseGap?: string): {
+    readonly initial: {
+        readonly height: 0;
+        readonly opacity: 0;
+        readonly marginTop: string;
+    };
+    readonly animate: {
+        readonly height: "auto";
+        readonly opacity: 1;
+        readonly marginTop: 0;
+    };
+    readonly exit: {
+        readonly height: 0;
+        readonly opacity: 0;
+        readonly marginTop: string;
+    };
+    readonly transition: {
+        readonly duration: 0;
+        readonly height?: undefined;
+        readonly marginTop?: undefined;
+        readonly opacity?: undefined;
+    } | {
+        readonly height: {
+            readonly type: "spring";
+            readonly stiffness: 400;
+            readonly damping: 40;
+        };
+        readonly marginTop: {
+            readonly type: "spring";
+            readonly stiffness: 400;
+            readonly damping: 40;
+        };
+        readonly opacity: {
+            readonly duration: 0.25;
+            readonly ease: "easeOut";
+        };
+        readonly duration?: undefined;
+    };
+};
 /**
  * The entrance recipe — rise `RISE_PX` on `SPRING_ENTRANCE` while
  * `FADE_ENTRANCE` brings the ink. What `Stack` and `Reveal` do; spread it

package/dist/src/utils/ghost-search.d.ts

@@ -1,11 +1,27 @@
-import { ComponentProps } from 'react';
+import { ComponentProps, ReactNode } from 'react';
 export interface GhostSearchProps extends Omit<ComponentProps<"input">, "value" | "onChange" | "type" | "children"> {
     value: string;
     onChange: (value: string) => void;
+    /**
+     * Empties the query from the field's own clear button, shown while it
+     * holds text; focus stays in the field. Without it, the browser's own
+     * clear glyph stays.
+     */
+    onClear?: () => void;
+    /** Quiet words at the field's end, before the clear button — a count. */
+    trailing?: ReactNode;
 }
 /**
  * A search box with no box: the glyph and the text on the surface's own
  * line, the way a toolbar band inside a card carries it (a `DataTable`'s
- * search, a `Trace.Waterfall`'s). Quiet ink, no ring until focus.
+ * search, a `Trace.Waterfall`'s, a `Scope`'s first row). Quiet ink, and no
+ * ring on focus either: a ring would draw the box the face exists not to
+ * have. Focus shows in the caret and in the magnifier, which takes the
+ * primary ink while the field holds focus.
+ *
+ * The query is the list's, not a form's: its change stops at the field, so
+ * an enclosing form that saves on change (BasicPage `Form autoSave`) or
+ * shows a save row once dirty never hears it. The type is an `sm` field's:
+ * 16px on small viewports, where iOS zooms into anything smaller.
  */
-export declare function GhostSearch({ value, onChange, className, ...props }: GhostSearchProps): import("react").JSX.Element;
+export declare function GhostSearch({ value, onChange, onClear, trailing, className, ref, ...props }: GhostSearchProps): import("react").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-ai/pho-ui",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "Pho Design System — Photon's React component library, built on Base UI",
   "license": "UNLICENSED",
   "repository": {
@@ -85,6 +85,10 @@
       "types": "./dist/src/components/checkbox/index.d.ts",
       "import": "./dist/components/checkbox.js"
     },
+    "./components/scope": {
+      "types": "./dist/src/components/scope/index.d.ts",
+      "import": "./dist/components/scope.js"
+    },
     "./components/radio-group": {
       "types": "./dist/src/components/radio-group/index.d.ts",
       "import": "./dist/components/radio-group.js"