@tulip-systems/core 0.8.3 → 0.10.0

package/dist/modules/commands/{utils → components/utils}/archive-command.client.d.mts

@@ -1,27 +1,19 @@
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { DefaultError, MutationOptions } from "@tanstack/react-query";
 
-//#region src/modules/commands/utils/archive-command.client.d.ts
+//#region src/modules/commands/components/utils/archive-command.client.d.ts
 type ArchiveCommandProps<TData = unknown, TError = DefaultError, TVariables = {
   ids: string[];
 }, TOnMutateResult = unknown> = {
   variables: TVariables;
   mutation: MutationOptions<TData, TError, TVariables, TOnMutateResult>;
 };
-/**
- * Archive command
- * @description command to archive a resource
- */
 declare function ArchiveCommand<TData = unknown, TError = DefaultError, TVariables = {
   ids: string[];
 }, TOnMutateResult = unknown>({
   variables,
   mutation
 }: ArchiveCommandProps<TData, TError, TVariables, TOnMutateResult>): react_jsx_runtime0.JSX.Element;
-/**
- * Unarchive command
- * @description command to unarchive a resource
- */
 declare function RestoreCommand<TData = unknown, TError = DefaultError, TVariables = {
   ids: string[];
 }, TOnMutateResult = unknown>({

package/dist/modules/commands/{utils → components/utils}/archive-command.client.mjs

@@ -1,15 +1,11 @@
 "use client";
 
-import { Icons } from "../../../components/common/icons.mjs";
-import { CommandLabel } from "../components/command-trigger.client.mjs";
-import { CommandClick } from "../components/click-command.client.mjs";
+import { Icons } from "../../../../components/common/icons.mjs";
+import { CommandLabel } from "../primitives/command-trigger.client.mjs";
+import { CommandClick } from "../primitives/click-command.client.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
-//#region src/modules/commands/utils/archive-command.client.tsx
-/**
-* Archive command
-* @description command to archive a resource
-*/
+//#region src/modules/commands/components/utils/archive-command.client.tsx
 function ArchiveCommand({ variables, mutation }) {
 	return /* @__PURE__ */ jsxs(CommandClick, {
 		variables,
@@ -19,10 +15,6 @@ function ArchiveCommand({ variables, mutation }) {
 		children: [/* @__PURE__ */ jsx(Icons.archive, { className: "w-4 text-destructive" }), /* @__PURE__ */ jsx(CommandLabel, {})]
 	});
 }
-/**
-* Unarchive command
-* @description command to unarchive a resource
-*/
 function RestoreCommand({ variables, mutation }) {
 	return /* @__PURE__ */ jsxs(CommandClick, {
 		className: "flex gap-2",

package/dist/modules/commands/{utils → components/utils}/delete-command.client.d.mts

@@ -1,22 +1,15 @@
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { DefaultError, MutationOptions } from "@tanstack/react-query";
 
-//#region src/modules/commands/utils/delete-command.client.d.ts
+//#region src/modules/commands/components/utils/delete-command.client.d.ts
 type DeleteCommandProps<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown> = {
   variables: TVariables;
   mutation: MutationOptions<TData, TError, TVariables, TOnMutateResult>;
 };
-/**
- * Delete command
- * @description command to delete a resource
- */
 declare function DeleteCommand<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown>({
   variables,
   mutation
 }: DeleteCommandProps<TData, TError, TVariables, TOnMutateResult>): react_jsx_runtime0.JSX.Element;
-/**
- * Single Delete command
- */
 declare function SingleDeleteCommand<TData = unknown, TError = DefaultError, TVariables = {
   id: string;
 }, TOnMutateResult = unknown>({

package/dist/modules/commands/{utils → components/utils}/delete-command.client.mjs

@@ -1,15 +1,11 @@
 "use client";
 
-import { Icons } from "../../../components/common/icons.mjs";
-import { CommandLabel } from "../components/command-trigger.client.mjs";
-import { CommandAlertDialog, CommandAlertDialogAction, CommandAlertDialogCancel, CommandAlertDialogContent, CommandAlertDialogDescription, CommandAlertDialogFooter, CommandAlertDialogHeader, CommandAlertDialogTitle, CommandAlertDialogTrigger } from "../components/alert-dialog-command.client.mjs";
+import { Icons } from "../../../../components/common/icons.mjs";
+import { CommandLabel } from "../primitives/command-trigger.client.mjs";
+import { CommandAlertDialog, CommandAlertDialogAction, CommandAlertDialogCancel, CommandAlertDialogContent, CommandAlertDialogDescription, CommandAlertDialogFooter, CommandAlertDialogHeader, CommandAlertDialogTitle, CommandAlertDialogTrigger } from "../primitives/alert-dialog-command.client.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
-//#region src/modules/commands/utils/delete-command.client.tsx
-/**
-* Delete command
-* @description command to delete a resource
-*/
+//#region src/modules/commands/components/utils/delete-command.client.tsx
 function DeleteCommand({ variables, mutation }) {
 	return /* @__PURE__ */ jsxs(CommandAlertDialog, { children: [/* @__PURE__ */ jsxs(CommandAlertDialogTrigger, {
 		className: "text-destructive",
@@ -21,9 +17,6 @@ function DeleteCommand({ variables, mutation }) {
 		children: "Verwijderen"
 	})] })] })] });
 }
-/**
-* Single Delete command
-*/
 function SingleDeleteCommand({ variables, mutation }) {
 	return /* @__PURE__ */ jsx(DeleteCommand, {
 		variables,

package/dist/modules/commands/hooks/use-command-mutation.client.d.mts

@@ -3,14 +3,9 @@ import * as _tanstack_react_query0 from "@tanstack/react-query";
 import { DefaultError, MutationOptions } from "@tanstack/react-query";
 
 //#region src/modules/commands/hooks/use-command-mutation.client.d.ts
-type CommandActionResult = Promise<unknown>;
-type CommandAction<TInput = void> = (input: TInput) => CommandActionResult;
-type BulkCommandAction = (params: {
-  ids: string[];
-}) => CommandActionResult;
 type CommandMutationMeta = {
   router: ReturnType<typeof useRouter>;
 };
 declare function useCommandMutation<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(options?: MutationOptions<TData, TError, TVariables, TOnMutateResult>): _tanstack_react_query0.UseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 //#endregion
-export { BulkCommandAction, CommandAction, CommandActionResult, CommandMutationMeta, useCommandMutation };
+export { CommandMutationMeta, useCommandMutation };

package/dist/modules/commands/hooks/use-command-mutation.client.mjs

@@ -1,10 +1,10 @@
 "use client";
 
 import { useAction } from "../../../lib/hooks/use-action.mjs";
-import { useCommand } from "./context.client.mjs";
+import { useCommand } from "./use-command.client.mjs";
 import { useRouter } from "next/navigation";
 
-//#region src/modules/commands/hooks/use-command-mutation.client.tsx
+//#region src/modules/commands/hooks/use-command-mutation.client.ts
 function useCommandMutation(options) {
 	const router = useRouter();
 	const commandContext = useCommand();
@@ -19,13 +19,11 @@ function useCommandMutation(options) {
 		onSuccess: async (...params) => {
 			const result = options?.onSuccess?.(...params);
 			commandContext.setStatus("success");
-			await commandContext.onSuccess?.();
 			return await result;
 		},
 		onError: async (...params) => {
 			const result = options?.onError?.(...params);
 			commandContext.setStatus("error");
-			await commandContext.onError?.();
 			return await result;
 		},
 		onSettled: async (...params) => {

package/dist/modules/commands/hooks/use-command.client.d.mts

@@ -0,0 +1,31 @@
+import { CommandStatus, CommandUI } from "../lib/builder.mjs";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { Dispatch, PropsWithChildren, SetStateAction } from "react";
+
+//#region src/modules/commands/hooks/use-command.client.d.ts
+type CommandContextValue = {
+  ui: CommandUI;
+  status: CommandStatus;
+  disabled: boolean;
+  setStatus: Dispatch<SetStateAction<CommandStatus>>;
+};
+declare function useCommand(): CommandContextValue;
+type CommandContextLifecycle = {
+  onSuccess?: () => Promise<void> | void;
+  onError?: () => Promise<void> | void;
+  onSettled?: () => Promise<void> | void;
+};
+type CommandContextProviderProps = PropsWithChildren<CommandContextLifecycle & {
+  ui: CommandUI;
+  disabled?: boolean;
+}>;
+declare function CommandContextProvider({
+  children,
+  ui,
+  disabled,
+  onSuccess,
+  onError,
+  onSettled
+}: CommandContextProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { CommandContextLifecycle, CommandContextProvider, useCommand };

package/dist/modules/commands/hooks/use-command.client.mjs

@@ -0,0 +1,45 @@
+"use client";
+
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+
+//#region src/modules/commands/hooks/use-command.client.tsx
+const CommandContext = createContext(null);
+function useCommand() {
+	const context = useContext(CommandContext);
+	if (!context) throw new Error("useCommand must be used within CommandContextProvider");
+	return context;
+}
+function CommandContextProvider({ children, ui, disabled = false, onSuccess, onError, onSettled }) {
+	const [status, setStatus] = useState("idle");
+	const previousStatusRef = useRef("idle");
+	useEffect(() => {
+		if (status === previousStatusRef.current) return;
+		if (status === "success") {
+			onSuccess?.();
+			onSettled?.();
+		}
+		if (status === "error") {
+			onError?.();
+			onSettled?.();
+		}
+		previousStatusRef.current = status;
+	}, [
+		status,
+		onSuccess,
+		onError,
+		onSettled
+	]);
+	return /* @__PURE__ */ jsx(CommandContext.Provider, {
+		value: {
+			ui,
+			status,
+			disabled,
+			setStatus
+		},
+		children
+	});
+}
+
+//#endregion
+export { CommandContextProvider, useCommand };

package/dist/modules/commands/lib/builder.d.mts

@@ -0,0 +1,135 @@
+import { Permission } from "../../auth/lib/permissions.mjs";
+
+//#region src/modules/commands/lib/builder.d.ts
+/**
+ * The different UI contexts in which a command can be rendered.
+ */
+type CommandUI = "dropdown" | "context" | "table" | "inline" | "custom";
+/**
+ * The status of a command, which can be used to style the command's UI appropriately.
+ */
+type CommandStatus = "idle" | "pending" | "success" | "error";
+/**
+ * A string tag that can be added to a command for organizational and filtering purposes.
+ */
+type CommandTag = string;
+/**
+ * Represents a command definition with its associated types and properties.
+ */
+type AnyCommandDef = CommandDef<any, any, any, any>;
+/**
+ * Condition function that determines whether a command is visible or disabled based on the provided data and meta.
+ */
+type CommandCondition<TData, TMeta> = (params: {
+  data: TData;
+  meta: TMeta;
+}) => boolean | boolean[];
+/**
+ * Render function that defines how a command should be rendered based on the provided data, meta, and UI context.
+ */
+type CommandRender<TData, TMeta> = (params: {
+  data: TData;
+  meta: TMeta;
+  ui: CommandUI;
+}) => React.ReactNode;
+/**
+ * Final command definition (without name).
+ * Name is derived from the object key in `defineCommands`.
+ *
+ * @typeParam TData  - The type `visibleWhen`, `disabledWhen`, and `render` receive.
+ *                    When `.transform()` is used this is the post-transform type.
+ * @typeParam TMeta  - Shared contextual metadata passed alongside data.
+ * @typeParam TTags  - Literal tuple of tag strings preserved from the builder's
+ *                    `.tags()` call. Enables compile-time tag filtering in the
+ *                    registry. Defaults to `string[]` when not provided.
+ * @typeParam TInput - The type that menus must pass as `data`. Equals `TData`
+ *                    when no `.transform()` is used. When `.transform(fn)` is
+ *                    called, `TInput` captures the pre-transform type so menus
+ *                    remain correctly typed while `render` sees the transformed type.
+ *                    Structurally expressed as the parameter of `transform`.
+ */
+type CommandDef<TData = unknown, TMeta = object, TTags extends readonly string[] = string[], TInput = TData> = {
+  id?: string;
+  tags: TTags;
+  transform?: (data: TInput) => TData;
+  permission?: Permission;
+  visibleWhen?: CommandCondition<TData, TMeta>;
+  disabledWhen?: CommandCondition<TData, TMeta>;
+  render: CommandRender<TData, TMeta>;
+};
+/**
+ * Command typed by accepted input data.
+ *
+ * Useful for APIs that only care about what can be passed in (e.g. table
+ * providers that always pass selected rows), not the command's normalized
+ * render-time shape.
+ */
+type CommandFor<TInput, TMeta = object> = CommandDef<any, TMeta, any, TInput>;
+/**
+ * Extracts the **input** data type of a command — what menus must pass as `data`.
+ *
+ * - When `.transform()` is used, this is the pre-transform type (e.g. `Template | Template[]`).
+ * - Otherwise it equals the render-time type.
+ *
+ * The type is read from the `transform` field's parameter when present, and
+ * falls back to the `render` parameter when there is no transformer.
+ */
+type ExtractCommandData<TCommand extends AnyCommandDef> = [NonNullable<TCommand["transform"]>] extends [never] ? TCommand extends {
+  render: (params: {
+    data: infer TData;
+    meta: any;
+    ui: any;
+  }) => any;
+} ? TData : never : NonNullable<TCommand["transform"]> extends ((data: infer TInput) => any) ? TInput : never;
+/**
+ * Builder state after `.$type<TData>()` has been called (or at initial state
+ * with `TData = unknown`).
+ *
+ * @typeParam TData  - Current render-time data type (post-transform if used).
+ * @typeParam TTags  - Literal tag tuple, carried through every method so that
+ *                    the final `CommandDef` retains the literal type.
+ * @typeParam TInput - Input data type for menus. Starts equal to `TData`.
+ *                    Freezes to the value of `TData` at the moment `.transform()`
+ *                    is called, while `TData` changes to the transformer's output.
+ */
+type ReadyCommandBuilder<TData, TMeta, TTags extends readonly string[] = string[], TInput = TData> = {
+  /** Override the data (and optionally meta) type. Resets `TInput` to the new `TData`. */$type<TNewData, TNewMeta = TMeta>(): ReadyCommandBuilder<TNewData, TNewMeta, TTags, TNewData>;
+  /**
+   * Set the command's tags as a literal tuple. The `const` modifier infers
+   * string arguments as literals, enabling compile-time tag narrowing in the registry.
+   */
+  tags<const TNewTags extends string[]>(...tags: TNewTags): ReadyCommandBuilder<TData, TMeta, TNewTags, TInput>;
+  permission(permission: Permission): ReadyCommandBuilder<TData, TMeta, TTags, TInput>;
+  /**
+   * Declares a lightweight transformer that runs once per render — before `visibleWhen`,
+   * `disabledWhen`, and `render` — collapsing the input type into a single usable shape.
+   *
+   * Freezes `TInput` to the current `TData` (the pre-transform type) and advances
+   * `TData` to `TNewData` (the transformer's return type). This ensures:
+   * - Menus are typed against the union input (e.g. `Template | Template[]`)
+   * - `visibleWhen` and `render` work with the clean transformed type (e.g. `Template[]`)
+   *
+   * @example
+   * commandBuilder
+   *   .$type<Template | Template[]>()
+   *   .transform((data) => (Array.isArray(data) ? data : [data]))
+   *   .visibleWhen(({ data }) => data.length > 0)  // data: Template[]
+   *   .render(({ data }) => <ArchiveCommand ids={data.map(i => i.id)} />)
+   */
+  transform<TNewData>(fn: (data: TData) => TNewData): ReadyCommandBuilder<TNewData, TMeta, TTags, TData>;
+  visibleWhen(condition: CommandCondition<TData, TMeta>): ReadyCommandBuilder<TData, TMeta, TTags, TInput>;
+  disabledWhen(condition: CommandCondition<TData, TMeta>): ReadyCommandBuilder<TData, TMeta, TTags, TInput>; /** Terminal — produces the final `CommandDef`. */
+  render(render: CommandRender<TData, TMeta>): CommandDef<TData, TMeta, TTags, TInput>;
+};
+/**
+ * The initial builder returned by `commandBuilder` / `createCommandBuilder()`.
+ * Before `.$type<>()` is called, `TData` is `unknown`.
+ */
+type InitialCommandBuilder<TMeta> = ReadyCommandBuilder<unknown, TMeta, string[], unknown> & {
+  $type<TNewData, TNewMeta = TMeta>(): ReadyCommandBuilder<TNewData, TNewMeta, string[], TNewData>;
+  tags<const TNewTags extends string[]>(...tags: TNewTags): ReadyCommandBuilder<unknown, TMeta, TNewTags, unknown>;
+};
+declare function createCommandBuilder<TMeta = object>(): InitialCommandBuilder<TMeta>;
+declare const commandBuilder: InitialCommandBuilder<object>;
+//#endregion
+export { AnyCommandDef, CommandCondition, CommandDef, CommandFor, CommandRender, CommandStatus, CommandTag, CommandUI, ExtractCommandData, commandBuilder, createCommandBuilder };

package/dist/modules/commands/lib/builder.mjs

@@ -0,0 +1,82 @@
+//#region src/modules/commands/lib/builder.ts
+function createInitialBuilder(state) {
+	return {
+		...createReadyBuilder({
+			tags: state.tags ?? [],
+			permission: state.permission
+		}),
+		tags(...tags) {
+			return createReadyBuilder({
+				tags,
+				permission: state.permission
+			});
+		},
+		$type() {
+			return createReadyBuilder({
+				tags: state.tags ?? [],
+				permission: state.permission
+			});
+		}
+	};
+}
+function createReadyBuilder(state) {
+	return {
+		$type() {
+			return createReadyBuilder({
+				tags: state.tags,
+				permission: state.permission
+			});
+		},
+		tags(...tags) {
+			return createReadyBuilder({
+				tags,
+				permission: state.permission,
+				transform: state.transform,
+				visibleWhen: state.visibleWhen,
+				disabledWhen: state.disabledWhen
+			});
+		},
+		permission(permission) {
+			return createReadyBuilder({
+				...state,
+				permission
+			});
+		},
+		transform(fn) {
+			return createReadyBuilder({
+				tags: state.tags,
+				permission: state.permission,
+				transform: fn
+			});
+		},
+		visibleWhen(condition) {
+			return createReadyBuilder({
+				...state,
+				visibleWhen: condition
+			});
+		},
+		disabledWhen(condition) {
+			return createReadyBuilder({
+				...state,
+				disabledWhen: condition
+			});
+		},
+		render(render) {
+			return {
+				tags: state.tags,
+				transform: state.transform,
+				permission: state.permission,
+				visibleWhen: state.visibleWhen,
+				disabledWhen: state.disabledWhen,
+				render
+			};
+		}
+	};
+}
+function createCommandBuilder() {
+	return createInitialBuilder({});
+}
+const commandBuilder = createCommandBuilder();
+
+//#endregion
+export { commandBuilder, createCommandBuilder };

package/dist/modules/commands/lib/registery.d.mts

@@ -0,0 +1,68 @@
+import { AnyCommandDef } from "./builder.mjs";
+
+//#region src/modules/commands/lib/registery.d.ts
+/**
+ * Command map type defining the shape of command definitions.
+ */
+type CommandMap = Record<string, AnyCommandDef>;
+/** Union of all values in a command map. */
+type ValueOf<TCommands extends CommandMap> = TCommands[keyof TCommands];
+/** Keep commands that have **every** of `TFilterTags`. */
+type FilterAllTags<TCommand extends AnyCommandDef, TFilterTags extends readonly string[]> = TCommand extends {
+  tags: infer CmdTags extends readonly string[];
+} ? TFilterTags[number] extends CmdTags[number] ? TCommand : never : TCommand;
+/** Keep commands that have **some** of `TFilterTags`. */
+type FilterAnyTags<TCommand extends AnyCommandDef, TFilterTags extends readonly string[]> = TCommand extends {
+  tags: infer CmdTags extends readonly string[];
+} ? string[] extends CmdTags ? TCommand : Extract<CmdTags[number], TFilterTags[number]> extends never ? never : TCommand : TCommand;
+/** Keep commands whose tag set equals `TFilterTags` (order-insensitive). */
+type FilterExactTags<TCommand extends AnyCommandDef, TFilterTags extends readonly string[]> = TCommand extends {
+  tags: infer CmdTags extends readonly string[];
+} ? string[] extends CmdTags ? TCommand : [CmdTags[number]] extends [TFilterTags[number]] ? [TFilterTags[number]] extends [CmdTags[number]] ? TCommand : never : never : TCommand;
+/** Keep commands that have **without** of `TFilterTags`. */
+type FilterWithoutTags<TCommand extends AnyCommandDef, TFilterTags extends readonly string[]> = TCommand extends {
+  tags: infer CmdTags extends readonly string[];
+} ? string[] extends CmdTags ? TCommand : Extract<CmdTags[number], TFilterTags[number]> extends never ? TCommand : never : TCommand;
+type CommandKey<TCommands extends CommandMap> = Extract<keyof TCommands, string>;
+type CommandFlags<TCommands extends CommandMap> = Partial<Record<CommandKey<TCommands>, boolean>>;
+type CommandInput<TCommands extends CommandMap> = readonly CommandKey<TCommands>[] | CommandFlags<TCommands>;
+type TruthyKeys<T> = { [K in keyof T]-?: T[K] extends true ? K : never }[keyof T];
+type PickedCommands<TCommands extends CommandMap, TInput extends CommandInput<TCommands>> = TInput extends readonly CommandKey<TCommands>[] ? Pick<TCommands, TInput[number]> : TInput extends CommandFlags<TCommands> ? Pick<TCommands, Extract<TruthyKeys<TInput>, keyof TCommands>> : never;
+type OmittedCommands<TCommands extends CommandMap, TInput extends CommandInput<TCommands>> = TInput extends readonly CommandKey<TCommands>[] ? Omit<TCommands, TInput[number]> : TInput extends CommandFlags<TCommands> ? Omit<TCommands, Extract<TruthyKeys<TInput>, keyof TCommands>> : never;
+type ExtendedCommands<TBase extends CommandMap, TExtension extends CommandMap> = Omit<TBase, keyof TExtension> & TExtension;
+type CommandTagFilterRegistry<TCommand extends AnyCommandDef> = {
+  every<const TTags extends string[]>(...tags: TTags): CommandTagFilterRegistry<FilterAllTags<TCommand, TTags>>;
+  some<const TTags extends string[]>(...tags: TTags): CommandTagFilterRegistry<FilterAnyTags<TCommand, TTags>>;
+  exact<const TTags extends string[]>(...tags: TTags): CommandTagFilterRegistry<FilterExactTags<TCommand, TTags>>;
+  without<const TTags extends string[]>(...tags: TTags): CommandTagFilterRegistry<FilterWithoutTags<TCommand, TTags>>;
+  toArray(): TCommand[];
+};
+type CommandKeyFilterRegistry<TCommands extends CommandMap> = {
+  pick<const TInput extends CommandInput<TCommands>>(input: TInput): CommandKeyFilterRegistry<PickedCommands<TCommands, TInput>>;
+  omit<const TInput extends CommandInput<TCommands>>(input: TInput): CommandKeyFilterRegistry<OmittedCommands<TCommands, TInput>>;
+  toArray(): ValueOf<TCommands>[];
+};
+type CommandRegistry<TCommands extends CommandMap> = {
+  commands: TCommands;
+  keys: CommandKeyFilterRegistry<TCommands>;
+  tags: CommandTagFilterRegistry<ValueOf<TCommands>>;
+  extend<const TExtension extends CommandMap>(extension: TExtension): CommandRegistry<ExtendedCommands<TCommands, TExtension>>; /** @deprecated Use `commands.keys.pick(...)` instead. */
+  pick<const TInput extends CommandInput<TCommands>>(input: TInput): CommandRegistry<PickedCommands<TCommands, TInput>>; /** @deprecated Use `commands.keys.omit(...)` instead. */
+  omit<const TInput extends CommandInput<TCommands>>(input: TInput): CommandRegistry<OmittedCommands<TCommands, TInput>>;
+  toArray(): ValueOf<TCommands>[];
+};
+/**
+ * Define commands from a map of name → `CommandDef`.
+ *
+ * Returns a `CommandRegistry` with key-based and tag-based filtering, plus
+ * `extend` for composition. Filter chains are immutable — each call produces
+ * a new registry.
+ *
+ * @example
+ * const registry = defineCommands({ edit, delete, archive });
+ * registry.tags.every("danger", "table").toArray();
+ * registry.keys.omit({ delete: true }).toArray();
+ */
+declare function defineCommands<TCommands extends CommandMap>(commands: TCommands): CommandRegistry<TCommands>;
+//#endregion
+export { CommandMap, defineCommands };

package/dist/modules/commands/lib/registery.mjs

@@ -0,0 +1,103 @@
+//#region src/modules/commands/lib/registery.ts
+function resolveKeys(input) {
+	if (Array.isArray(input)) return [...input];
+	return Object.entries(input).filter(([, enabled]) => enabled === true).map(([key]) => key);
+}
+function dedupe(tags) {
+	return [...new Set(tags)];
+}
+function hasEveryTag(command, tags) {
+	return tags.every((tag) => command.tags.includes(tag));
+}
+function hasSomeTag(command, tags) {
+	return tags.some((tag) => command.tags.includes(tag));
+}
+function hasExactTags(command, tags) {
+	const ctags = dedupe(command.tags);
+	const ftags = dedupe(tags);
+	return ctags.length === ftags.length && ftags.every((t) => ctags.includes(t));
+}
+function injectIds(commands) {
+	return Object.fromEntries(Object.entries(commands).map(([id, c]) => [id, {
+		...c,
+		id
+	}]));
+}
+function pickCommands(commands, input) {
+	const keys = resolveKeys(input);
+	return Object.fromEntries(keys.filter((k) => k in commands).map((k) => [k, commands[k]]));
+}
+function omitCommands(commands, input) {
+	const keys = new Set(resolveKeys(input));
+	return Object.fromEntries(Object.entries(commands).filter(([k]) => !keys.has(k)));
+}
+function createTagFilterRegistry(commands) {
+	function apply(predicate) {
+		return (...tags) => {
+			return createTagFilterRegistry(commands.filter((c) => predicate(c, tags)));
+		};
+	}
+	return {
+		every: apply(hasEveryTag),
+		some: apply(hasSomeTag),
+		exact: apply(hasExactTags),
+		without: apply((c, ts) => !hasSomeTag(c, ts)),
+		toArray() {
+			return commands;
+		}
+	};
+}
+function createKeyFilterRegistry(commands) {
+	return {
+		pick(input) {
+			return createKeyFilterRegistry(pickCommands(commands, input));
+		},
+		omit(input) {
+			return createKeyFilterRegistry(omitCommands(commands, input));
+		},
+		toArray() {
+			return Object.values(commands);
+		}
+	};
+}
+function createRegistry(commands) {
+	const withIds = injectIds(commands);
+	return {
+		commands: withIds,
+		keys: createKeyFilterRegistry(withIds),
+		tags: createTagFilterRegistry(Object.values(withIds)),
+		extend(extension) {
+			return createRegistry({
+				...withIds,
+				...extension
+			});
+		},
+		pick(input) {
+			return createRegistry(pickCommands(withIds, input));
+		},
+		omit(input) {
+			return createRegistry(omitCommands(withIds, input));
+		},
+		toArray() {
+			return Object.values(withIds);
+		}
+	};
+}
+/**
+* Define commands from a map of name → `CommandDef`.
+*
+* Returns a `CommandRegistry` with key-based and tag-based filtering, plus
+* `extend` for composition. Filter chains are immutable — each call produces
+* a new registry.
+*
+* @example
+* const registry = defineCommands({ edit, delete, archive });
+* registry.tags.every("danger", "table").toArray();
+* registry.keys.omit({ delete: true }).toArray();
+*/
+function defineCommands(commands) {
+	return createRegistry(commands);
+}
+
+//#endregion
+export { defineCommands };

package/dist/modules/commands/lib/utils.d.mts

@@ -0,0 +1,11 @@
+//#region src/modules/commands/lib/utils.d.ts
+/**
+ * Normalizes command data into an array.
+ *
+ * Use this as a command transform when the same command should support both
+ * single-item and bulk contexts. After `.transform(ensureArray)`, command
+ * callbacks can safely use array helpers like `.map` and `.every`.
+ */
+declare function ensureArray<T>(data: T | T[]): T[];
+//#endregion
+export { ensureArray };

package/dist/modules/commands/lib/utils.mjs

@@ -0,0 +1,14 @@
+//#region src/modules/commands/lib/utils.ts
+/**
+* Normalizes command data into an array.
+*
+* Use this as a command transform when the same command should support both
+* single-item and bulk contexts. After `.transform(ensureArray)`, command
+* callbacks can safely use array helpers like `.map` and `.every`.
+*/
+function ensureArray(data) {
+	return Array.isArray(data) ? data : [data];
+}
+
+//#endregion
+export { ensureArray };