@elaraai/east-ui 1.0.67 → 1.0.69

package/dist/src/contracts/pick.d.ts

@@ -0,0 +1,705 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The PICK contract (#590) — which of a component's declared things are shown.
+ *
+ * A Plan picks row series, a Table would pick columns, a Chart layers. The
+ * operation is the same one every time: a library of identified things, some
+ * switched off, the survivors fed back to the component. This module is the one
+ * place that vocabulary is spelled; `Pick.Panel` renders it and never imports a
+ * component, exactly as `Slice.Rail` mounts anywhere.
+ *
+ * # Why it splits in two
+ *
+ * A `UIComponentType` arm must be a CLOSED East type, so the panel cannot ride
+ * a generic. That is not a stylistic call — it is why {@link SliceLegendType}
+ * carries `SliceBindType` and not `SliceBindType<T>`. Pick therefore splits at
+ * exactly the point where the item type stops mattering:
+ *
+ * - {@link PickBindType} is NON-GENERIC — a key, a state binding, and a list of
+ *   plain-data descriptors. It is the only part that enters the IR, so ONE
+ *   panel arm serves every component that ever adopts this.
+ * - {@link PickHandleType} is the AUTHOR's handle, and never enters the IR.
+ *   `I` rides STRUCTURALLY (in `all` and `id`), the way `C` rides in
+ *   {@link PagedSourceType}'s `page` signature, so a handle bound to one item
+ *   type is a compile error against a component expecting another.
+ *
+ * # Why no platform function
+ *
+ * `state` is literally {@link State.bind}'s `{read, write, has}` pinned at
+ * {@link PickStateType}. Pick declares nothing of its own, so it needs neither
+ * of the two re-export hops in `east-ui-components` nor the two hard-coded
+ * arrays in `e3-ui-components` — the documented "ships broken while tests pass"
+ * trap. It also means {@link Pick.active} is provable in a plain `describeEast`
+ * spec rather than only in a browser.
+ *
+ * # Why the state is what is HIDDEN
+ *
+ * Storing the active list looks equivalent and is not: a thing the author adds
+ * in a later release is absent from every user's persisted state, so it
+ * silently never appears. Storing what is switched OFF means new arrivals show
+ * by default and only explicit removals persist — the same reason `Slice`
+ * stores `visible: Option<Set>` with `none` meaning all, minus the `Option`,
+ * because an empty HIDDEN list is unambiguous where an empty VISIBLE set is not.
+ *
+ * # What this contract deliberately does NOT do
+ *
+ * It does not ORDER. On a key-ordered surface there is nothing for an order to
+ * order: a Plan's rows sit in canonical KEY order (`PlanRowsCollectionType` is
+ * a `Dict`, and `applySeries` unions with LAST_WINS), so a series' position in
+ * the list resolves key collisions and never row position. The panel's own list
+ * order is already `all`'s array order. Ordering becomes real for an adopter
+ * whose collection is positional — a Table's columns — and belongs to that
+ * adopter, not here.
+ *
+ * @packageDocumentation
+ */
+import { type EastType, type ExprType, type SubtypeExprOrValue, ArrayType, BooleanType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType } from "@elaraai/east";
+import { IconType } from "../display/icon/types.js";
+/**
+ * The pick state — the ids switched OFF. An empty list shows everything.
+ *
+ * @remarks
+ * Deliberately the hidden ids rather than the active ones, and deliberately a
+ * bare `Array<String>` rather than a struct: there is exactly one fact to
+ * store. See this module's overview for why hidden beats active.
+ *
+ * Duplicates are harmless ({@link Pick.active} tests membership through a set)
+ * and an id that no longer names anything is ignored, so persisted state
+ * survives an author renaming or removing an item.
+ */
+export declare const PickStateType: ArrayType<StringType>;
+/** Type alias for {@link PickStateType}. */
+export type PickStateType = typeof PickStateType;
+/**
+ * One pickable thing as the PANEL sees it — plain data, no item type.
+ *
+ * @remarks
+ * This is the whole of what a panel can render, which is what keeps the panel
+ * component-agnostic: it never learns what a "series" or a "column" is.
+ *
+ * @property id - Stable identity — what the state addresses and what `id` returns; must be unique across the list
+ * @property title - The name a user reads (`"Machine jobs"`)
+ * @property subtitle - The muted role line (`"one row per machine"`); `none` ⇒ one-line row
+ * @property icon - The leading glyph; `none` ⇒ the panel prints no icon
+ * @property count - How many things this yields (`"24 rs"`); `none` ⇒ no count printed, which is what a paged source must say
+ * @property narrowed - `true` ⇒ the count is a NARROWED count, printed in the brand with a dot
+ */
+export declare const PickItemType: StructType<{
+    readonly id: StringType;
+    readonly title: StringType;
+    readonly subtitle: OptionType<StringType>;
+    readonly icon: OptionType<StructType<{
+        readonly name: StringType;
+        readonly prefix: StringType;
+        readonly label: OptionType<StringType>;
+        readonly style: OptionType<StructType<{
+            readonly size: OptionType<import("@elaraai/east").VariantType<{
+                readonly xs: NullType;
+                readonly sm: NullType;
+                readonly md: NullType;
+                readonly lg: NullType;
+                readonly xl: NullType;
+                readonly "2xl": NullType;
+            }>>;
+            readonly variant: OptionType<import("@elaraai/east").VariantType<{
+                readonly solid: NullType;
+                readonly regular: NullType;
+                readonly light: NullType;
+                readonly thin: NullType;
+                readonly brands: NullType;
+            }>>;
+            readonly color: OptionType<StringType>;
+            readonly background: OptionType<StringType>;
+            readonly colorPalette: OptionType<import("@elaraai/east").VariantType<{
+                readonly brand: NullType;
+                readonly gray: NullType;
+                readonly red: NullType;
+                readonly orange: NullType;
+                readonly yellow: NullType;
+                readonly green: NullType;
+                readonly teal: NullType;
+                readonly blue: NullType;
+                readonly cyan: NullType;
+                readonly purple: NullType;
+                readonly pink: NullType;
+                readonly success: NullType;
+                readonly warning: NullType;
+                readonly danger: NullType;
+                readonly info: NullType;
+                readonly neutral: NullType;
+            }>>;
+            readonly opacity: OptionType<import("@elaraai/east").FloatType>;
+            readonly borderRadius: OptionType<StringType>;
+            readonly overflow: OptionType<import("@elaraai/east").VariantType<{
+                readonly visible: NullType;
+                readonly hidden: NullType;
+                readonly scroll: NullType;
+                readonly auto: NullType;
+            }>>;
+            readonly overflowX: OptionType<import("@elaraai/east").VariantType<{
+                readonly visible: NullType;
+                readonly hidden: NullType;
+                readonly scroll: NullType;
+                readonly auto: NullType;
+            }>>;
+            readonly overflowY: OptionType<import("@elaraai/east").VariantType<{
+                readonly visible: NullType;
+                readonly hidden: NullType;
+                readonly scroll: NullType;
+                readonly auto: NullType;
+            }>>;
+            readonly width: OptionType<StringType>;
+            readonly height: OptionType<StringType>;
+            readonly minWidth: OptionType<StringType>;
+            readonly minHeight: OptionType<StringType>;
+            readonly maxWidth: OptionType<StringType>;
+            readonly maxHeight: OptionType<StringType>;
+            readonly padding: OptionType<StructType<{
+                readonly top: OptionType<StringType>;
+                readonly right: OptionType<StringType>;
+                readonly bottom: OptionType<StringType>;
+                readonly left: OptionType<StringType>;
+            }>>;
+            readonly margin: OptionType<StructType<{
+                readonly top: OptionType<StringType>;
+                readonly right: OptionType<StringType>;
+                readonly bottom: OptionType<StringType>;
+                readonly left: OptionType<StringType>;
+            }>>;
+        }>>;
+    }>>;
+    readonly count: OptionType<IntegerType>;
+    readonly narrowed: BooleanType;
+}>;
+/** Type alias for {@link PickItemType}. */
+export type PickItemType = typeof PickItemType;
+/**
+ * The state binding a pick carries — EXACTLY {@link State.bind}'s return type,
+ * pinned at {@link PickStateType}.
+ *
+ * @remarks
+ * Field order matters and is `read` / `write` / `has`, because East struct
+ * subtyping is exact — same arity, same names, same order. Declaring it here
+ * rather than re-deriving it means a change to `State.bind`'s shape fails this
+ * file's build rather than something downstream.
+ *
+ * Nothing bespoke is introduced: per #106 a bind handle's methods are
+ * IR-bearing East functions over plain-data primitives, so a pick handle is
+ * ordinary serializable East data and `decodeBeast2For({ platform })` re-binds
+ * it to the decoder's store.
+ *
+ * @property read - The current state; TRACKS the key, so it belongs in a reactive evaluation
+ * @property write - Replace the state
+ * @property has - Whether the key is set
+ */
+export declare const PickStateHandleType: StructType<{
+    readonly read: FunctionType<[], ArrayType<StringType>>;
+    readonly write: FunctionType<[ArrayType<StringType>], NullType>;
+    readonly has: FunctionType<[], BooleanType>;
+}>;
+/** Type alias for {@link PickStateHandleType}. */
+export type PickStateHandleType = typeof PickStateHandleType;
+/**
+ * THE CONTRACT — what a panel stores and what any component's IR may hold.
+ *
+ * @remarks
+ * Non-generic by construction, so it embeds directly in a `UIComponentType`
+ * arm. A renderer needs nothing else: `key` to self-subscribe, `state` to read
+ * and write, `items` to draw.
+ *
+ * `items` is an EXPRESSION (`all.map(describe)`), not a build-time snapshot, so
+ * a count derived from data re-evaluates every reactive frame instead of
+ * freezing at authoring time.
+ *
+ * @property key - The store key; renderers self-subscribe on it, like `SliceBindType.key`
+ * @property state - The {@link PickStateHandleType} binding
+ * @property items - Every pickable thing, in declaration order
+ */
+export declare const PickBindType: StructType<{
+    readonly key: StringType;
+    readonly state: StructType<{
+        readonly read: FunctionType<[], ArrayType<StringType>>;
+        readonly write: FunctionType<[ArrayType<StringType>], NullType>;
+        readonly has: FunctionType<[], BooleanType>;
+    }>;
+    readonly items: ArrayType<StructType<{
+        readonly id: StringType;
+        readonly title: StringType;
+        readonly subtitle: OptionType<StringType>;
+        readonly icon: OptionType<StructType<{
+            readonly name: StringType;
+            readonly prefix: StringType;
+            readonly label: OptionType<StringType>;
+            readonly style: OptionType<StructType<{
+                readonly size: OptionType<import("@elaraai/east").VariantType<{
+                    readonly xs: NullType;
+                    readonly sm: NullType;
+                    readonly md: NullType;
+                    readonly lg: NullType;
+                    readonly xl: NullType;
+                    readonly "2xl": NullType;
+                }>>;
+                readonly variant: OptionType<import("@elaraai/east").VariantType<{
+                    readonly solid: NullType;
+                    readonly regular: NullType;
+                    readonly light: NullType;
+                    readonly thin: NullType;
+                    readonly brands: NullType;
+                }>>;
+                readonly color: OptionType<StringType>;
+                readonly background: OptionType<StringType>;
+                readonly colorPalette: OptionType<import("@elaraai/east").VariantType<{
+                    readonly brand: NullType;
+                    readonly gray: NullType;
+                    readonly red: NullType;
+                    readonly orange: NullType;
+                    readonly yellow: NullType;
+                    readonly green: NullType;
+                    readonly teal: NullType;
+                    readonly blue: NullType;
+                    readonly cyan: NullType;
+                    readonly purple: NullType;
+                    readonly pink: NullType;
+                    readonly success: NullType;
+                    readonly warning: NullType;
+                    readonly danger: NullType;
+                    readonly info: NullType;
+                    readonly neutral: NullType;
+                }>>;
+                readonly opacity: OptionType<import("@elaraai/east").FloatType>;
+                readonly borderRadius: OptionType<StringType>;
+                readonly overflow: OptionType<import("@elaraai/east").VariantType<{
+                    readonly visible: NullType;
+                    readonly hidden: NullType;
+                    readonly scroll: NullType;
+                    readonly auto: NullType;
+                }>>;
+                readonly overflowX: OptionType<import("@elaraai/east").VariantType<{
+                    readonly visible: NullType;
+                    readonly hidden: NullType;
+                    readonly scroll: NullType;
+                    readonly auto: NullType;
+                }>>;
+                readonly overflowY: OptionType<import("@elaraai/east").VariantType<{
+                    readonly visible: NullType;
+                    readonly hidden: NullType;
+                    readonly scroll: NullType;
+                    readonly auto: NullType;
+                }>>;
+                readonly width: OptionType<StringType>;
+                readonly height: OptionType<StringType>;
+                readonly minWidth: OptionType<StringType>;
+                readonly minHeight: OptionType<StringType>;
+                readonly maxWidth: OptionType<StringType>;
+                readonly maxHeight: OptionType<StringType>;
+                readonly padding: OptionType<StructType<{
+                    readonly top: OptionType<StringType>;
+                    readonly right: OptionType<StringType>;
+                    readonly bottom: OptionType<StringType>;
+                    readonly left: OptionType<StringType>;
+                }>>;
+                readonly margin: OptionType<StructType<{
+                    readonly top: OptionType<StringType>;
+                    readonly right: OptionType<StringType>;
+                    readonly bottom: OptionType<StringType>;
+                    readonly left: OptionType<StringType>;
+                }>>;
+            }>>;
+        }>>;
+        readonly count: OptionType<IntegerType>;
+        readonly narrowed: BooleanType;
+    }>>;
+}>;
+/** Type alias for {@link PickBindType}. */
+export type PickBindType = typeof PickBindType;
+/**
+ * The `Pick.Panel` component payload — the contract plus the author's noun.
+ *
+ * @remarks
+ * Defined HERE rather than inline in `component.ts` because it carries no
+ * `UIComponentType`: only arms that need the recursion `node` for children have
+ * to be written inline (and then hand-synced). `SliceLegendType` is legal as a
+ * single shared export for exactly the same reason, and this follows it.
+ *
+ * `persist` is deliberately absent. The slice's storage vocabulary
+ * (`SlicePersistType`) lives in `platform/slice`, which imports FROM
+ * `contracts/` — referencing it here would close an import cycle. Persistence
+ * beyond the store's own lifetime is a separate decision, made where the
+ * dependency runs the right way.
+ *
+ * @property pick - The bound contract ({@link PickBindType})
+ * @property title - The author's noun for the collection ("Series" / "Columns")
+ */
+export declare const PickPanelType: StructType<{
+    readonly pick: StructType<{
+        readonly key: StringType;
+        readonly state: StructType<{
+            readonly read: FunctionType<[], ArrayType<StringType>>;
+            readonly write: FunctionType<[ArrayType<StringType>], NullType>;
+            readonly has: FunctionType<[], BooleanType>;
+        }>;
+        readonly items: ArrayType<StructType<{
+            readonly id: StringType;
+            readonly title: StringType;
+            readonly subtitle: OptionType<StringType>;
+            readonly icon: OptionType<StructType<{
+                readonly name: StringType;
+                readonly prefix: StringType;
+                readonly label: OptionType<StringType>;
+                readonly style: OptionType<StructType<{
+                    readonly size: OptionType<import("@elaraai/east").VariantType<{
+                        readonly xs: NullType;
+                        readonly sm: NullType;
+                        readonly md: NullType;
+                        readonly lg: NullType;
+                        readonly xl: NullType;
+                        readonly "2xl": NullType;
+                    }>>;
+                    readonly variant: OptionType<import("@elaraai/east").VariantType<{
+                        readonly solid: NullType;
+                        readonly regular: NullType;
+                        readonly light: NullType;
+                        readonly thin: NullType;
+                        readonly brands: NullType;
+                    }>>;
+                    readonly color: OptionType<StringType>;
+                    readonly background: OptionType<StringType>;
+                    readonly colorPalette: OptionType<import("@elaraai/east").VariantType<{
+                        readonly brand: NullType;
+                        readonly gray: NullType;
+                        readonly red: NullType;
+                        readonly orange: NullType;
+                        readonly yellow: NullType;
+                        readonly green: NullType;
+                        readonly teal: NullType;
+                        readonly blue: NullType;
+                        readonly cyan: NullType;
+                        readonly purple: NullType;
+                        readonly pink: NullType;
+                        readonly success: NullType;
+                        readonly warning: NullType;
+                        readonly danger: NullType;
+                        readonly info: NullType;
+                        readonly neutral: NullType;
+                    }>>;
+                    readonly opacity: OptionType<import("@elaraai/east").FloatType>;
+                    readonly borderRadius: OptionType<StringType>;
+                    readonly overflow: OptionType<import("@elaraai/east").VariantType<{
+                        readonly visible: NullType;
+                        readonly hidden: NullType;
+                        readonly scroll: NullType;
+                        readonly auto: NullType;
+                    }>>;
+                    readonly overflowX: OptionType<import("@elaraai/east").VariantType<{
+                        readonly visible: NullType;
+                        readonly hidden: NullType;
+                        readonly scroll: NullType;
+                        readonly auto: NullType;
+                    }>>;
+                    readonly overflowY: OptionType<import("@elaraai/east").VariantType<{
+                        readonly visible: NullType;
+                        readonly hidden: NullType;
+                        readonly scroll: NullType;
+                        readonly auto: NullType;
+                    }>>;
+                    readonly width: OptionType<StringType>;
+                    readonly height: OptionType<StringType>;
+                    readonly minWidth: OptionType<StringType>;
+                    readonly minHeight: OptionType<StringType>;
+                    readonly maxWidth: OptionType<StringType>;
+                    readonly maxHeight: OptionType<StringType>;
+                    readonly padding: OptionType<StructType<{
+                        readonly top: OptionType<StringType>;
+                        readonly right: OptionType<StringType>;
+                        readonly bottom: OptionType<StringType>;
+                        readonly left: OptionType<StringType>;
+                    }>>;
+                    readonly margin: OptionType<StructType<{
+                        readonly top: OptionType<StringType>;
+                        readonly right: OptionType<StringType>;
+                        readonly bottom: OptionType<StringType>;
+                        readonly left: OptionType<StringType>;
+                    }>>;
+                }>>;
+            }>>;
+            readonly count: OptionType<IntegerType>;
+            readonly narrowed: BooleanType;
+        }>>;
+    }>;
+    readonly title: StringType;
+}>;
+/** Type alias for {@link PickPanelType}. */
+export type PickPanelType = typeof PickPanelType;
+/**
+ * The AUTHOR's handle — the contract plus the typed things it selects over.
+ *
+ * @remarks
+ * Never enters the IR. `all` and `id` are what carry `I`, structurally, so the
+ * type flows from `Pick.bind` to `Pick.active` and back into the component
+ * without a phantom brand and without surviving into a closed arm.
+ *
+ * @typeParam I - The item type being picked over
+ * @param i - The item type value
+ * @returns The concrete `StructType` of a handle over `i`
+ *
+ * @property pick - The non-generic contract handed to {@link Pick.Panel}
+ * @property all - Every item that COULD show, in declaration order
+ * @property id - An item's stable id — the same one its {@link PickItemType} carries
+ */
+export declare const PickHandleType: <I extends EastType>(i: I) => StructType<{
+    readonly pick: StructType<{
+        readonly key: StringType;
+        readonly state: StructType<{
+            readonly read: FunctionType<[], ArrayType<StringType>>;
+            readonly write: FunctionType<[ArrayType<StringType>], NullType>;
+            readonly has: FunctionType<[], BooleanType>;
+        }>;
+        readonly items: ArrayType<StructType<{
+            readonly id: StringType;
+            readonly title: StringType;
+            readonly subtitle: OptionType<StringType>;
+            readonly icon: OptionType<StructType<{
+                readonly name: StringType;
+                readonly prefix: StringType;
+                readonly label: OptionType<StringType>;
+                readonly style: OptionType<StructType<{
+                    readonly size: OptionType<import("@elaraai/east").VariantType<{
+                        readonly xs: NullType;
+                        readonly sm: NullType;
+                        readonly md: NullType;
+                        readonly lg: NullType;
+                        readonly xl: NullType;
+                        readonly "2xl": NullType;
+                    }>>;
+                    readonly variant: OptionType<import("@elaraai/east").VariantType<{
+                        readonly solid: NullType;
+                        readonly regular: NullType;
+                        readonly light: NullType;
+                        readonly thin: NullType;
+                        readonly brands: NullType;
+                    }>>;
+                    readonly color: OptionType<StringType>;
+                    readonly background: OptionType<StringType>;
+                    readonly colorPalette: OptionType<import("@elaraai/east").VariantType<{
+                        readonly brand: NullType;
+                        readonly gray: NullType;
+                        readonly red: NullType;
+                        readonly orange: NullType;
+                        readonly yellow: NullType;
+                        readonly green: NullType;
+                        readonly teal: NullType;
+                        readonly blue: NullType;
+                        readonly cyan: NullType;
+                        readonly purple: NullType;
+                        readonly pink: NullType;
+                        readonly success: NullType;
+                        readonly warning: NullType;
+                        readonly danger: NullType;
+                        readonly info: NullType;
+                        readonly neutral: NullType;
+                    }>>;
+                    readonly opacity: OptionType<import("@elaraai/east").FloatType>;
+                    readonly borderRadius: OptionType<StringType>;
+                    readonly overflow: OptionType<import("@elaraai/east").VariantType<{
+                        readonly visible: NullType;
+                        readonly hidden: NullType;
+                        readonly scroll: NullType;
+                        readonly auto: NullType;
+                    }>>;
+                    readonly overflowX: OptionType<import("@elaraai/east").VariantType<{
+                        readonly visible: NullType;
+                        readonly hidden: NullType;
+                        readonly scroll: NullType;
+                        readonly auto: NullType;
+                    }>>;
+                    readonly overflowY: OptionType<import("@elaraai/east").VariantType<{
+                        readonly visible: NullType;
+                        readonly hidden: NullType;
+                        readonly scroll: NullType;
+                        readonly auto: NullType;
+                    }>>;
+                    readonly width: OptionType<StringType>;
+                    readonly height: OptionType<StringType>;
+                    readonly minWidth: OptionType<StringType>;
+                    readonly minHeight: OptionType<StringType>;
+                    readonly maxWidth: OptionType<StringType>;
+                    readonly maxHeight: OptionType<StringType>;
+                    readonly padding: OptionType<StructType<{
+                        readonly top: OptionType<StringType>;
+                        readonly right: OptionType<StringType>;
+                        readonly bottom: OptionType<StringType>;
+                        readonly left: OptionType<StringType>;
+                    }>>;
+                    readonly margin: OptionType<StructType<{
+                        readonly top: OptionType<StringType>;
+                        readonly right: OptionType<StringType>;
+                        readonly bottom: OptionType<StringType>;
+                        readonly left: OptionType<StringType>;
+                    }>>;
+                }>>;
+            }>>;
+            readonly count: OptionType<IntegerType>;
+            readonly narrowed: BooleanType;
+        }>>;
+    }>;
+    readonly all: ArrayType<I>;
+    readonly id: FunctionType<[I], StringType>;
+}>;
+/**
+ * The TypeScript type of a {@link PickHandleType} over item type `I`.
+ *
+ * @typeParam I - The item type being picked over
+ */
+export type PickHandle<I extends EastType> = ExprType<ReturnType<typeof PickHandleType<I>>>;
+/**
+ * How one item describes itself to the panel — the accessors {@link Pick.bind}
+ * reifies.
+ *
+ * @remarks
+ * `id` and `title` are required because a thing with no identity cannot be
+ * persisted and a thing with no name cannot be offered to a user. Everything
+ * else is presentation the panel degrades gracefully without.
+ *
+ * @typeParam I - The item type being picked over
+ */
+export interface PickOptions<I extends EastType> {
+    /**
+     * The item's stable id — what the state addresses.
+     *
+     * @remarks
+     * Must be UNIQUE across `all`. The hidden set is a list of ids, so two
+     * items sharing one are a single switch wearing two labels: toggling either
+     * hides both, and a persisted id cannot say which was meant. `Pick.Panel`
+     * reports a duplicate in development rather than resolving it — dropping
+     * one would silently remove an item that is still in the FEED, since
+     * {@link Pick.active} filters the item list rather than the descriptors.
+     */
+    id: (item: ExprType<I>) => SubtypeExprOrValue<StringType>;
+    /** The name a user reads. */
+    title: (item: ExprType<I>) => SubtypeExprOrValue<StringType>;
+    /** The muted role line — return the field's `Option`. */
+    subtitle?: (item: ExprType<I>) => SubtypeExprOrValue<OptionType<StringType>>;
+    /** The leading glyph — return the field's `Option`. */
+    icon?: (item: ExprType<I>) => SubtypeExprOrValue<OptionType<IconType>>;
+    /** How many things this item yields — return the field's `Option`; `none` when the source is paged and cannot know. */
+    count?: (item: ExprType<I>) => SubtypeExprOrValue<OptionType<IntegerType>>;
+    /** `true` ⇒ the count is a narrowed count. */
+    narrowed?: (item: ExprType<I>) => SubtypeExprOrValue<BooleanType>;
+    /** Ids switched off to begin with; omit ⇒ everything shows. */
+    hidden?: readonly string[];
+}
+/**
+ * Build a {@link PickStateType} seed.
+ *
+ * @param hidden - The ids switched off; omit ⇒ everything shows
+ * @returns The state expression
+ *
+ * @example
+ * ```ts
+ * Pick.state()                 // everything shows
+ * Pick.state(["crew"])         // "crew" starts switched off
+ * ```
+ */
+export declare function createPickState(hidden?: readonly string[]): ExprType<PickStateType>;
+/**
+ * Bind a list of things to a persisted pick.
+ *
+ * @remarks
+ * Takes NO item-type argument — `I` is already carried by `all`, recovered with
+ * the `Expr.type` idiom, so the call reads the way the author thinks about it.
+ *
+ * The accessors are REIFIED once into a single describe function which the map
+ * then CALLS, per the factory rule (`shared/reify.ts`, `EAST_UI_PROP_PATTERNS.md`)
+ * — never invoked mid-map with their expression trees spliced in.
+ *
+ * Bind exactly ONCE, in the same reactive evaluation that mounts both the panel
+ * and the component. A `Reactive.Root` body is a free function and cannot
+ * capture a `$.let` handle from an enclosing scope, so a panel that is its own
+ * root would need its own bind — two binds on one key work (they share the
+ * store) but must be given identical item lists, or the two surfaces disagree
+ * about what exists.
+ *
+ * @typeParam I - The item type being picked over
+ * @param key - The store key; also the persistence key
+ * @param all - Every item that COULD show — an expression of `Array<I>`
+ * @param options - The per-item accessors and the seed ({@link PickOptions})
+ * @returns A {@link PickHandleType} over `I`
+ *
+ * @example
+ * ```tsx
+ * const shown = $.let(Pick.bind("orders.cols", cols, {
+ *     id:    c => c.key,
+ *     title: c => c.header,
+ *     hidden: ["price"],
+ * }));
+ *
+ * <Pick.Panel value={shown} title="Columns" />
+ * <Table data={orders} columns={Pick.active(shown)} />
+ * ```
+ */
+/**
+ * The library entries alone — every item described, with NO state binding.
+ *
+ * @remarks
+ * {@link Pick.bind} builds `items` with exactly this call, so proving one
+ * proves the other. It is split out for the same reason {@link pickVisible} is:
+ * `State.bind` is not runnable in a `describeEast` spec, and the descriptor
+ * derivation — identity, icons, counts — is the part worth testing.
+ *
+ * Useful in its own right when a host wants to render its own list rather than
+ * mount `Pick.Panel`.
+ *
+ * @typeParam I - The item type being picked over
+ * @param all - Every item that COULD show
+ * @param options - The per-item accessors ({@link PickOptions})
+ * @returns The descriptors, in declaration order
+ */
+export declare function pickItems<I extends EastType>(all: SubtypeExprOrValue<ArrayType<I>>, options: PickOptions<I>): ExprType<ArrayType<PickItemType>>;
+export declare function createPickBind<I extends EastType>(key: string, all: SubtypeExprOrValue<ArrayType<I>>, options: PickOptions<I>): PickHandle<I>;
+/**
+ * The items still switched on, in DECLARATION order — the feed a component takes.
+ *
+ * @remarks
+ * The twin of `Slice.rows(...)`: one tracked read, one derivation, and the
+ * result is an ordinary expression the component's own prop already accepts.
+ * For a Plan that means `series={Pick.active(shown)}` needs no Plan change at
+ * all, because `PlanSeriesInput` already accepts the expression form.
+ *
+ * Declaration order, never the state's — see this module's overview. An id in
+ * the state that names nothing is ignored, so a rename or removal degrades to
+ * "shown" rather than to an error.
+ *
+ * Call this INSIDE the reactive evaluation that renders the component: the read
+ * is what registers the dependency that repaints on a toggle.
+ *
+ * @typeParam I - The item type being picked over
+ * @param handle - The handle from {@link Pick.bind}
+ * @returns The surviving items, as `Array<I>`
+ */
+export declare function pickActive<I extends EastType>(handle: PickHandle<I>): ExprType<ArrayType<I>>;
+/**
+ * The derivation on its own — items minus a hidden list, with NO state binding.
+ *
+ * @remarks
+ * {@link Pick.active} is this plus one tracked read, so proving this proves the
+ * shipped behaviour. It exists split out because the semantics are the part
+ * worth testing and `State.bind` is not runnable in a `describeEast` spec —
+ * `TestImpl` carries no State runtime (`test/platform/state.spec.ts` is
+ * compile-only for exactly this reason). Here the hidden list is a plain value,
+ * so the whole contract is provable with no platform function at all.
+ *
+ * Three behaviours it fixes, all of them things a bare `active` list gets
+ * wrong: declaration order is preserved, an id naming nothing is ignored, and
+ * an item absent from the list still shows.
+ *
+ * @typeParam I - The item type being picked over
+ * @param all - Every item that COULD show
+ * @param id - An item's stable id
+ * @param hidden - The ids switched off
+ * @returns The surviving items, in declaration order
+ */
+export declare function pickVisible<I extends EastType>(all: SubtypeExprOrValue<ArrayType<I>>, id: SubtypeExprOrValue<FunctionType<[I], StringType>>, hidden: SubtypeExprOrValue<PickStateType>): ExprType<ArrayType<I>>;
+//# sourceMappingURL=pick.d.ts.map