@ai-matrx/records-ui 0.93.132 → 0.93.140

package/dist/objectActions-BSbblgf-.d.cts

@@ -0,0 +1,168 @@
+import { PermissionLevel, Table } from '@ai-matrx/records';
+
+/** The six things a person does to a record or a table, as the screens offer them. */
+type Capability = "read" | "comment" | "write" | "remove" | "share" | "structure";
+interface WhatYouMayDo {
+    /** The word the store answered, or null when it answered nothing. */
+    level: PermissionLevel | null;
+    /**
+     * Whether the store has ANSWERED yet. `false` is a third state and not a
+     * refusal: a screen that drew "you may not" while the answer was in flight
+     * would blink every control off on every reload, which is its own lie.
+     */
+    known: boolean;
+    read: boolean;
+    comment: boolean;
+    write: boolean;
+    remove: boolean;
+    share: boolean;
+    structure: boolean;
+    /** Why this person may not do that, in one sentence naming the way in. */
+    why: (what: Capability) => string;
+}
+/** What each rung of the ladder is called where a person reads it. */
+declare const LEVEL_WORD: Record<PermissionLevel, string>;
+/** The rung a capability asks for — so a short "Needs Admin access" never re-decides the ladder. */
+declare function levelNeededFor(what: Capability): PermissionLevel;
+/**
+ * WHAT ONE LEVEL LETS A PERSON DO. `level` null and `known` true means the
+ * store said "nothing" — a real answer. `known` false means it has not said.
+ */
+declare function whatYouMayDo(level: PermissionLevel | null, known?: boolean): WhatYouMayDo;
+/** Nothing offered, because nothing is known yet. */
+declare const NOT_ANSWERED_YET: WhatYouMayDo;
+/**
+ * REC-27. The nine Tables the platform ships are not administered from a
+ * person's screen whatever level they hold on them — so the structure controls
+ * are absent for a kernel Table and say why, and everything else follows the
+ * level as usual.
+ */
+declare const KERNEL_REASON: string;
+declare function whatYouMayDoWithTable(table: Table | null | undefined, level: PermissionLevel | null, known: boolean): WhatYouMayDo;
+
+/**
+ * A Lucide icon NAME, kebab-case — the same currency `Table.icon` already uses.
+ * Closed on purpose: each renderer maps every member to its own component, and a
+ * new member fails that renderer's typecheck until it is mapped.
+ */
+type ObjectActionIcon = "folder-open" | "external-link" | "link" | "pencil" | "copy" | "folder-input" | "star" | "star-off" | "share-2" | "download" | "upload" | "columns-3" | "settings" | "history" | "blocks" | "file-text" | "calendar-clock" | "list-checks" | "bell" | "door-open" | "inbox" | "layout-dashboard" | "archive-restore" | "archive" | "link-2" | "layout-grid";
+/** The groups, in their one order. Separators fall out of group boundaries. */
+type ObjectActionGroup = "open" | "organize" | "share" | "manage" | "built-on" | "danger";
+interface ObjectActionGroupDef {
+    id: ObjectActionGroup;
+    /** Present only on a group that renders as a submenu. */
+    label?: string;
+    icon?: ObjectActionIcon;
+    /** Rendered as ONE submenu entry holding the group's actions. */
+    submenu: boolean;
+}
+declare const OBJECT_ACTION_GROUPS: readonly ObjectActionGroupDef[];
+/** One thing a person can do to an object, for any renderer. */
+interface ObjectAction {
+    /** Stable within the object's list. React key, test handle, future ⌘K id. */
+    id: string;
+    label: string;
+    icon: ObjectActionIcon;
+    group: ObjectActionGroup;
+    /** Display-only hint ("⌘D"). */
+    shortcut?: string;
+    destructive?: boolean;
+    /** Present = shown disabled with this line (≤ 60 chars). Absent = enabled. */
+    disabledReason?: string;
+    /** Called only when enabled. The host owns the side effect and its feedback. */
+    run: () => void | Promise<void>;
+}
+/** What the list needs to know about the table. A full `Table` satisfies it. */
+type TableActionSubject = Pick<Table, "id" | "name"> & Partial<Pick<Table, "is_kernel">>;
+/** The places built on a table, in their one order. */
+type BuiltOnDestination = "forms" | "bookings" | "checklists" | "notifications" | "portals" | "inbox" | "dashboards" | "archived";
+type Handler = (table: TableActionSubject) => void | Promise<void>;
+/**
+ * THE SIDE EFFECTS THIS PACKAGE CANNOT OWN. Every handler is optional: one the
+ * host leaves out keeps its action in the list, disabled, saying so.
+ */
+interface TableActionHost {
+    /** Origin for Copy link and Open in new tab. Default `https://www.aimatrx.com`. */
+    origin?: string;
+    open?: Handler;
+    /** Receives the table's link (`<origin>/data-v2/<id>`). */
+    openInNewTab?: (url: string, table: TableActionSubject) => void;
+    /** Receives the table's link. Runs inside the click (clipboard needs the gesture). */
+    copyText?: (text: string, table: TableActionSubject) => void | Promise<void>;
+    rename?: Handler;
+    duplicate?: Handler;
+    move?: Handler;
+    /** Current favorite state; flips the Favorite label. Unknown = "Add to favorites". */
+    isFavorite?: boolean;
+    toggleFavorite?: Handler;
+    share?: Handler;
+    export?: Handler;
+    import?: Handler;
+    addColumn?: Handler;
+    settings?: Handler;
+    history?: Handler;
+    /** The "Built on it" destinations, one handler for all eight. */
+    openBuiltOn?: (destination: BuiltOnDestination, table: TableActionSubject) => void;
+    archive?: Handler;
+    /**
+     * ANOTHER LANE'S ENTRIES ("Link a record…", a hub tile's verbs). Return the
+     * same ids whatever `rights` say — express rights as `disabledReason`. Each
+     * entry lands at the END of its named group, in the order returned; `danger`
+     * is refused (Archive is always last) and so is an id already in the list.
+     */
+    extend?: (table: TableActionSubject, rights: WhatYouMayDo) => readonly ObjectAction[];
+}
+interface TableActionsInput {
+    table: TableActionSubject;
+    rights: WhatYouMayDo;
+    host: TableActionHost;
+}
+declare const DEFAULT_ACTION_ORIGIN = "https://www.aimatrx.com";
+/** The one link to a table: `<origin>/data-v2/<tableId>`. */
+declare function tableLink(tableId: string, origin?: string): string;
+declare const ACTION_NOT_HERE_REASON = "Not available here";
+declare const ACTION_CHECKING_ACCESS_REASON = "Checking your access\u2026";
+declare const ACTION_NO_ACCESS_REASON = "You don't have access";
+declare const ACTION_PLATFORM_TABLE_REASON = "Platform tables can't be changed here";
+/** Why `rights` refuse `what`, in one short line — or null when they allow it. */
+declare function rightsReason(rights: WhatYouMayDo, what: Capability, table?: TableActionSubject): string | null;
+/**
+ * THE TABLE'S ACTIONS, in the one order. Same ids, same order, for every seat
+ * and every host — only `disabledReason` varies.
+ */
+declare function tableActions(input: TableActionsInput): ObjectAction[];
+/**
+ * Another lane's entries, placed deterministically: each at the end of its
+ * group, in the order given. Loud on the two mistakes that would break the
+ * invariants — a `danger` entry (Archive must stay last) and a duplicate id.
+ */
+declare function withExtensions(base: readonly ObjectAction[], extra: readonly ObjectAction[]): ObjectAction[];
+/** A run of actions that renders together: a plain section, or one submenu. */
+interface ObjectActionSection {
+    group: ObjectActionGroupDef;
+    actions: ObjectAction[];
+}
+/**
+ * THE ONE GROUPING every adapter uses: the list cut at group boundaries, in
+ * group order, empty groups dropped, the order inside a group kept.
+ */
+declare function groupObjectActions(actions: readonly ObjectAction[]): ObjectActionSection[];
+/** The header ⋯ dropdown's entries — records-ui's own renderer reads these. */
+type ObjectActionDropdownEntry = {
+    kind: "separator";
+    id: string;
+} | {
+    kind: "item";
+    action: ObjectAction;
+} | {
+    kind: "submenu";
+    id: string;
+    label: string;
+    icon: ObjectActionIcon | undefined;
+    actions: ObjectAction[];
+};
+declare function toDropdownEntries(actions: readonly ObjectAction[]): ObjectActionDropdownEntry[];
+/** The action ids a dropdown draws, in order — what G1 compares. */
+declare function dropdownActionIds(entries: readonly ObjectActionDropdownEntry[]): string[];
+
+export { ACTION_CHECKING_ACCESS_REASON as A, type BuiltOnDestination as B, type Capability as C, DEFAULT_ACTION_ORIGIN as D, KERNEL_REASON as K, LEVEL_WORD as L, NOT_ANSWERED_YET as N, type ObjectAction as O, type TableActionHost as T, type WhatYouMayDo as W, ACTION_NOT_HERE_REASON as a, ACTION_NO_ACCESS_REASON as b, ACTION_PLATFORM_TABLE_REASON as c, OBJECT_ACTION_GROUPS as d, type ObjectActionDropdownEntry as e, type ObjectActionGroup as f, type ObjectActionGroupDef as g, type ObjectActionIcon as h, type ObjectActionSection as i, type TableActionSubject as j, type TableActionsInput as k, dropdownActionIds as l, groupObjectActions as m, levelNeededFor as n, tableLink as o, toDropdownEntries as p, whatYouMayDoWithTable as q, rightsReason as r, withExtensions as s, tableActions as t, whatYouMayDo as w };

package/dist/objectActions-BSbblgf-.d.ts

@@ -0,0 +1,168 @@
+import { PermissionLevel, Table } from '@ai-matrx/records';
+
+/** The six things a person does to a record or a table, as the screens offer them. */
+type Capability = "read" | "comment" | "write" | "remove" | "share" | "structure";
+interface WhatYouMayDo {
+    /** The word the store answered, or null when it answered nothing. */
+    level: PermissionLevel | null;
+    /**
+     * Whether the store has ANSWERED yet. `false` is a third state and not a
+     * refusal: a screen that drew "you may not" while the answer was in flight
+     * would blink every control off on every reload, which is its own lie.
+     */
+    known: boolean;
+    read: boolean;
+    comment: boolean;
+    write: boolean;
+    remove: boolean;
+    share: boolean;
+    structure: boolean;
+    /** Why this person may not do that, in one sentence naming the way in. */
+    why: (what: Capability) => string;
+}
+/** What each rung of the ladder is called where a person reads it. */
+declare const LEVEL_WORD: Record<PermissionLevel, string>;
+/** The rung a capability asks for — so a short "Needs Admin access" never re-decides the ladder. */
+declare function levelNeededFor(what: Capability): PermissionLevel;
+/**
+ * WHAT ONE LEVEL LETS A PERSON DO. `level` null and `known` true means the
+ * store said "nothing" — a real answer. `known` false means it has not said.
+ */
+declare function whatYouMayDo(level: PermissionLevel | null, known?: boolean): WhatYouMayDo;
+/** Nothing offered, because nothing is known yet. */
+declare const NOT_ANSWERED_YET: WhatYouMayDo;
+/**
+ * REC-27. The nine Tables the platform ships are not administered from a
+ * person's screen whatever level they hold on them — so the structure controls
+ * are absent for a kernel Table and say why, and everything else follows the
+ * level as usual.
+ */
+declare const KERNEL_REASON: string;
+declare function whatYouMayDoWithTable(table: Table | null | undefined, level: PermissionLevel | null, known: boolean): WhatYouMayDo;
+
+/**
+ * A Lucide icon NAME, kebab-case — the same currency `Table.icon` already uses.
+ * Closed on purpose: each renderer maps every member to its own component, and a
+ * new member fails that renderer's typecheck until it is mapped.
+ */
+type ObjectActionIcon = "folder-open" | "external-link" | "link" | "pencil" | "copy" | "folder-input" | "star" | "star-off" | "share-2" | "download" | "upload" | "columns-3" | "settings" | "history" | "blocks" | "file-text" | "calendar-clock" | "list-checks" | "bell" | "door-open" | "inbox" | "layout-dashboard" | "archive-restore" | "archive" | "link-2" | "layout-grid";
+/** The groups, in their one order. Separators fall out of group boundaries. */
+type ObjectActionGroup = "open" | "organize" | "share" | "manage" | "built-on" | "danger";
+interface ObjectActionGroupDef {
+    id: ObjectActionGroup;
+    /** Present only on a group that renders as a submenu. */
+    label?: string;
+    icon?: ObjectActionIcon;
+    /** Rendered as ONE submenu entry holding the group's actions. */
+    submenu: boolean;
+}
+declare const OBJECT_ACTION_GROUPS: readonly ObjectActionGroupDef[];
+/** One thing a person can do to an object, for any renderer. */
+interface ObjectAction {
+    /** Stable within the object's list. React key, test handle, future ⌘K id. */
+    id: string;
+    label: string;
+    icon: ObjectActionIcon;
+    group: ObjectActionGroup;
+    /** Display-only hint ("⌘D"). */
+    shortcut?: string;
+    destructive?: boolean;
+    /** Present = shown disabled with this line (≤ 60 chars). Absent = enabled. */
+    disabledReason?: string;
+    /** Called only when enabled. The host owns the side effect and its feedback. */
+    run: () => void | Promise<void>;
+}
+/** What the list needs to know about the table. A full `Table` satisfies it. */
+type TableActionSubject = Pick<Table, "id" | "name"> & Partial<Pick<Table, "is_kernel">>;
+/** The places built on a table, in their one order. */
+type BuiltOnDestination = "forms" | "bookings" | "checklists" | "notifications" | "portals" | "inbox" | "dashboards" | "archived";
+type Handler = (table: TableActionSubject) => void | Promise<void>;
+/**
+ * THE SIDE EFFECTS THIS PACKAGE CANNOT OWN. Every handler is optional: one the
+ * host leaves out keeps its action in the list, disabled, saying so.
+ */
+interface TableActionHost {
+    /** Origin for Copy link and Open in new tab. Default `https://www.aimatrx.com`. */
+    origin?: string;
+    open?: Handler;
+    /** Receives the table's link (`<origin>/data-v2/<id>`). */
+    openInNewTab?: (url: string, table: TableActionSubject) => void;
+    /** Receives the table's link. Runs inside the click (clipboard needs the gesture). */
+    copyText?: (text: string, table: TableActionSubject) => void | Promise<void>;
+    rename?: Handler;
+    duplicate?: Handler;
+    move?: Handler;
+    /** Current favorite state; flips the Favorite label. Unknown = "Add to favorites". */
+    isFavorite?: boolean;
+    toggleFavorite?: Handler;
+    share?: Handler;
+    export?: Handler;
+    import?: Handler;
+    addColumn?: Handler;
+    settings?: Handler;
+    history?: Handler;
+    /** The "Built on it" destinations, one handler for all eight. */
+    openBuiltOn?: (destination: BuiltOnDestination, table: TableActionSubject) => void;
+    archive?: Handler;
+    /**
+     * ANOTHER LANE'S ENTRIES ("Link a record…", a hub tile's verbs). Return the
+     * same ids whatever `rights` say — express rights as `disabledReason`. Each
+     * entry lands at the END of its named group, in the order returned; `danger`
+     * is refused (Archive is always last) and so is an id already in the list.
+     */
+    extend?: (table: TableActionSubject, rights: WhatYouMayDo) => readonly ObjectAction[];
+}
+interface TableActionsInput {
+    table: TableActionSubject;
+    rights: WhatYouMayDo;
+    host: TableActionHost;
+}
+declare const DEFAULT_ACTION_ORIGIN = "https://www.aimatrx.com";
+/** The one link to a table: `<origin>/data-v2/<tableId>`. */
+declare function tableLink(tableId: string, origin?: string): string;
+declare const ACTION_NOT_HERE_REASON = "Not available here";
+declare const ACTION_CHECKING_ACCESS_REASON = "Checking your access\u2026";
+declare const ACTION_NO_ACCESS_REASON = "You don't have access";
+declare const ACTION_PLATFORM_TABLE_REASON = "Platform tables can't be changed here";
+/** Why `rights` refuse `what`, in one short line — or null when they allow it. */
+declare function rightsReason(rights: WhatYouMayDo, what: Capability, table?: TableActionSubject): string | null;
+/**
+ * THE TABLE'S ACTIONS, in the one order. Same ids, same order, for every seat
+ * and every host — only `disabledReason` varies.
+ */
+declare function tableActions(input: TableActionsInput): ObjectAction[];
+/**
+ * Another lane's entries, placed deterministically: each at the end of its
+ * group, in the order given. Loud on the two mistakes that would break the
+ * invariants — a `danger` entry (Archive must stay last) and a duplicate id.
+ */
+declare function withExtensions(base: readonly ObjectAction[], extra: readonly ObjectAction[]): ObjectAction[];
+/** A run of actions that renders together: a plain section, or one submenu. */
+interface ObjectActionSection {
+    group: ObjectActionGroupDef;
+    actions: ObjectAction[];
+}
+/**
+ * THE ONE GROUPING every adapter uses: the list cut at group boundaries, in
+ * group order, empty groups dropped, the order inside a group kept.
+ */
+declare function groupObjectActions(actions: readonly ObjectAction[]): ObjectActionSection[];
+/** The header ⋯ dropdown's entries — records-ui's own renderer reads these. */
+type ObjectActionDropdownEntry = {
+    kind: "separator";
+    id: string;
+} | {
+    kind: "item";
+    action: ObjectAction;
+} | {
+    kind: "submenu";
+    id: string;
+    label: string;
+    icon: ObjectActionIcon | undefined;
+    actions: ObjectAction[];
+};
+declare function toDropdownEntries(actions: readonly ObjectAction[]): ObjectActionDropdownEntry[];
+/** The action ids a dropdown draws, in order — what G1 compares. */
+declare function dropdownActionIds(entries: readonly ObjectActionDropdownEntry[]): string[];
+
+export { ACTION_CHECKING_ACCESS_REASON as A, type BuiltOnDestination as B, type Capability as C, DEFAULT_ACTION_ORIGIN as D, KERNEL_REASON as K, LEVEL_WORD as L, NOT_ANSWERED_YET as N, type ObjectAction as O, type TableActionHost as T, type WhatYouMayDo as W, ACTION_NOT_HERE_REASON as a, ACTION_NO_ACCESS_REASON as b, ACTION_PLATFORM_TABLE_REASON as c, OBJECT_ACTION_GROUPS as d, type ObjectActionDropdownEntry as e, type ObjectActionGroup as f, type ObjectActionGroupDef as g, type ObjectActionIcon as h, type ObjectActionSection as i, type TableActionSubject as j, type TableActionsInput as k, dropdownActionIds as l, groupObjectActions as m, levelNeededFor as n, tableLink as o, toDropdownEntries as p, whatYouMayDoWithTable as q, rightsReason as r, withExtensions as s, tableActions as t, whatYouMayDo as w };