@tulip-systems/core 0.9.0 → 0.10.0

package/src/modules/commands/components/menus/inline-menu.client.tsx

@@ -1,25 +1,24 @@
 "use client";
 
 import type { ComponentProps, HTMLAttributes, ReactNode } from "react";
-import type z from "zod";
 import { Skeleton } from "@/components/entry";
 import { cn } from "@/lib/utils/cn";
 import type { CommandContextLifecycle } from "../../hooks/use-command.client";
-import type { CommandDef } from "../../lib/builder";
+import type { AnyCommandDef, CommandDef, ExtractCommandData } from "../../lib/builder";
 import { RenderCommand } from "../render-command";
 
 export type InlineCommandMenuProps<
-  TSchema extends z.ZodTypeAny,
-  TMeta,
+  TCommand extends AnyCommandDef,
+  TMeta = object,
 > = HTMLAttributes<HTMLElement> &
   CommandContextLifecycle & {
-    data: unknown;
-    commands: Array<CommandDef<z.ZodTypeAny, TMeta>>;
+    data: NoInfer<ExtractCommandData<TCommand>>;
+    commands: TCommand[];
     meta?: TMeta;
     fallback?: ReactNode;
   };
 
-export function InlineCommandMenu<TSchema extends z.ZodTypeAny, TMeta>({
+export function InlineCommandMenu<TCommand extends AnyCommandDef, TMeta = object>({
   data,
   meta,
   commands,
@@ -29,7 +28,7 @@ export function InlineCommandMenu<TSchema extends z.ZodTypeAny, TMeta>({
   onSettled,
   className,
   ...props
-}: InlineCommandMenuProps<TSchema, TMeta>) {
+}: InlineCommandMenuProps<TCommand, TMeta>) {
   if (!commands.length) return null;
 
   return (
@@ -38,8 +37,8 @@ export function InlineCommandMenu<TSchema extends z.ZodTypeAny, TMeta>({
         {commands.map((command, index) => (
           <RenderCommand
             key={index}
-            command={command}
-            data={data}
+            command={command as CommandDef<unknown, TMeta>}
+            data={data as unknown}
             meta={meta}
             fallback={fallback}
             ui="inline"

package/src/modules/commands/components/menus/responsive-menu.client.tsx

@@ -1,24 +1,23 @@
 "use client";
 
 import type { ReactNode } from "react";
-import type z from "zod";
 import type { CommandContextLifecycle } from "../../hooks/use-command.client";
-import type { CommandDef } from "../../lib/builder";
+import type { AnyCommandDef, ExtractCommandData } from "../../lib/builder";
 import { DropdownCommandMenu, DropdownCommandMenuLoading } from "./dropdown-menu.client";
 import { InlineCommandMenu, InlineCommandMenuLoading } from "./inline-menu.client";
 
 export type ResponsiveCommandMenuProps<
-  TSchema extends z.ZodTypeAny,
-  TMeta,
+  TCommand extends AnyCommandDef,
+  TMeta = object,
 > = CommandContextLifecycle & {
-  data: unknown;
-  commands: Array<CommandDef<z.ZodTypeAny, TMeta>>;
+  data: NoInfer<ExtractCommandData<TCommand>>;
+  commands: TCommand[];
   meta?: TMeta;
   fallback?: ReactNode;
 };
 
-export function ResponsiveCommandMenu<TSchema extends z.ZodTypeAny, TMeta>(
-  props: ResponsiveCommandMenuProps<TSchema, TMeta>,
+export function ResponsiveCommandMenu<TCommand extends AnyCommandDef, TMeta = object>(
+  props: ResponsiveCommandMenuProps<TCommand, TMeta>,
 ) {
   return (
     <>

package/src/modules/commands/components/render-command.tsx

@@ -1,14 +1,13 @@
 "use client";
 
 import type { ReactNode } from "react";
-import type z from "zod";
 import { Allowed } from "@/modules/auth/components/allowed.client";
 import { type CommandContextLifecycle, CommandContextProvider } from "../hooks/use-command.client";
 import type { CommandDef, CommandUI } from "../lib/builder";
 
-type RenderCommandProps<TSchema extends z.ZodTypeAny, TMeta> = {
-  command: CommandDef<TSchema, TMeta>;
-  data: z.input<TSchema>;
+type RenderCommandProps<TData, TMeta> = {
+  command: CommandDef<TData, TMeta>;
+  data: TData;
   meta?: TMeta;
   fallback?: ReactNode;
   ui: CommandUI;
@@ -17,22 +16,27 @@ type RenderCommandProps<TSchema extends z.ZodTypeAny, TMeta> = {
 /**
  * Command renderer.
  *
- * It validates input data through the command schema, applies optional visibility/disabled rules,
- * exposes command status via context, and then renders the command content.
+ * It applies cheap visibility/disabled rules, exposes command status via context,
+ * and then renders the command content. Validation belongs at execution boundaries.
  */
-export function RenderCommand<TSchema extends z.ZodTypeAny, TMeta>(
-  props: RenderCommandProps<TSchema, TMeta>,
-) {
-  const parsedData = props.command.schema.safeParse(props.data);
-  if (!parsedData.success) return <>{props.fallback}</>;
-  const data = parsedData.data;
+export function RenderCommand<TData, TMeta>(props: RenderCommandProps<TData, TMeta>) {
+  // Apply the command's transformer once before dispatching to conditions and render.
+  // This lets commands declare a union input type (e.g. Template | Template[]) while
+  // working with a single transformed type (e.g. Template[]) internally.
+  const data = (
+    props.command.transform
+      ? (props.command.transform as (data: unknown) => unknown)(props.data)
+      : props.data
+  ) as TData;
 
   const meta = (props.meta ?? {}) as TMeta;
 
   const visibleResult = props.command.visibleWhen?.({ data, meta });
   const disabledResult = props.command.disabledWhen?.({ data, meta });
 
-  const isVisible = Array.isArray(visibleResult) ? visibleResult.every(Boolean) : (visibleResult ?? true);
+  const isVisible = Array.isArray(visibleResult)
+    ? visibleResult.every(Boolean)
+    : (visibleResult ?? true);
   if (!isVisible) return <>{props.fallback}</>;
 
   const isDisabled = Array.isArray(disabledResult)

package/src/modules/commands/entry.ts

@@ -3,3 +3,4 @@
  */
 export * from "./lib/builder";
 export * from "./lib/registery";
+export * from "./lib/utils";

package/src/modules/commands/lib/builder.ts

@@ -1,17 +1,39 @@
-import type { z } from "zod";
 import type { Permission } from "@/modules/auth/lib/permissions";
 
+/**
+ * The different UI contexts in which a command can be rendered.
+ */
 export type CommandUI = "dropdown" | "context" | "table" | "inline" | "custom";
 
+/**
+ * The status of a command, which can be used to style the command's UI appropriately.
+ */
 export type CommandStatus = "idle" | "pending" | "success" | "error";
 
-export type CommandCondition<TSchema extends z.ZodTypeAny, TMeta> = (params: {
-  data: z.output<TSchema>;
+/**
+ * A string tag that can be added to a command for organizational and filtering purposes.
+ */
+export type CommandTag = string;
+
+/**
+ * Represents a command definition with its associated types and properties.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: intentional — holds heterogeneous command data/meta/tag types.
+export 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.
+ */
+export type CommandCondition<TData, TMeta> = (params: {
+  data: TData;
   meta: TMeta;
 }) => boolean | boolean[];
 
-export type CommandRender<TSchema extends z.ZodTypeAny, TMeta> = (params: {
-  data: z.output<TSchema>;
+/**
+ * Render function that defines how a command should be rendered based on the provided data, meta, and UI context.
+ */
+export type CommandRender<TData, TMeta> = (params: {
+  data: TData;
   meta: TMeta;
   ui: CommandUI;
 }) => React.ReactNode;
@@ -19,69 +41,227 @@ export type CommandRender<TSchema extends z.ZodTypeAny, TMeta> = (params: {
 /**
  * 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`.
  */
-export type CommandDef<TSchema extends z.ZodTypeAny = z.ZodTypeAny, TMeta = object> = {
+export type CommandDef<
+  TData = unknown,
+  TMeta = object,
+  TTags extends readonly string[] = string[],
+  TInput = TData,
+> = {
+  id?: string;
+  tags: TTags;
+  transform?: (data: TInput) => TData;
   permission?: Permission;
-  schema: TSchema;
-  visibleWhen?: CommandCondition<TSchema, TMeta>;
-  disabledWhen?: CommandCondition<TSchema, TMeta>;
-  render: CommandRender<TSchema, TMeta>;
+  visibleWhen?: CommandCondition<TData, TMeta>;
+  disabledWhen?: CommandCondition<TData, TMeta>;
+  render: CommandRender<TData, TMeta>;
 };
 
-type ReadyCommandBuilder<TSchema extends z.ZodTypeAny, TMeta> = {
-  permission(permission: Permission): ReadyCommandBuilder<TSchema, TMeta>;
-  visibleWhen(condition: CommandCondition<TSchema, TMeta>): ReadyCommandBuilder<TSchema, TMeta>;
-  disabledWhen(condition: CommandCondition<TSchema, TMeta>): ReadyCommandBuilder<TSchema, TMeta>;
-  render(render: CommandRender<TSchema, TMeta>): CommandDef<TSchema, 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.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: hides non-input generics for call-site ergonomics.
+export 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.
+ */
+export 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 interfaces ────────────────────────────────────────────────────────
+
+/**
+ * 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>;
 };
 
-type InitialCommandBuilder<TMeta> = {
-  input<TNextSchema extends z.ZodTypeAny>(schema: TNextSchema): ReadyCommandBuilder<TNextSchema, TMeta>;
+/**
+ * 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>;
 };
 
+// ─── Internal builder state ────────────────────────────────────────────────────
+
 type StartState<TMeta> = {
+  tags?: readonly string[];
   permission?: Permission;
   meta?: TMeta;
 };
 
-type ReadyState<TSchema extends z.ZodTypeAny, TMeta> = {
+type ReadyState<TData, TMeta, TTags extends readonly string[]> = {
+  tags: TTags;
   permission?: Permission;
-  schema: TSchema;
-  visibleWhen?: CommandCondition<TSchema, TMeta>;
-  disabledWhen?: CommandCondition<TSchema, TMeta>;
+  // Erased to (data: unknown) => unknown at storage level; CommandDef.transform is typed as
+  // CommandNormalize<TInput, TData> and restored via cast in the render() terminal.
+  transform?: (data: unknown) => unknown;
+  visibleWhen?: CommandCondition<TData, TMeta>;
+  disabledWhen?: CommandCondition<TData, TMeta>;
 };
 
+// ─── Builder factory functions ─────────────────────────────────────────────────
+
 function createInitialBuilder<TMeta>(state: StartState<TMeta>): InitialCommandBuilder<TMeta> {
+  const readyBuilder = createReadyBuilder<unknown, TMeta, string[]>({
+    tags: (state.tags as string[]) ?? [],
+    permission: state.permission,
+  });
+
   return {
-    input<TNextSchema extends z.ZodTypeAny>(schema: TNextSchema) {
-      return createReadyBuilder<TNextSchema, TMeta>({ permission: state.permission, schema });
+    ...readyBuilder,
+    tags<const TNewTags extends string[]>(...tags: TNewTags) {
+      return createReadyBuilder<unknown, TMeta, TNewTags>({
+        tags,
+        permission: state.permission,
+      });
+    },
+    $type<TNewData, TNewMeta = TMeta>() {
+      return createReadyBuilder<TNewData, TNewMeta, string[]>({
+        tags: (state.tags as string[]) ?? [],
+        permission: state.permission,
+      });
     },
-  };
+  } as InitialCommandBuilder<TMeta>;
 }
 
-function createReadyBuilder<TSchema extends z.ZodTypeAny, TMeta>(
-  state: ReadyState<TSchema, TMeta>,
-): ReadyCommandBuilder<TSchema, TMeta> {
+function createReadyBuilder<TData, TMeta, TTags extends readonly string[]>(
+  state: ReadyState<TData, TMeta, TTags>,
+): ReadyCommandBuilder<TData, TMeta, TTags, TData> {
   return {
+    $type<TNewData, TNewMeta = TMeta>() {
+      return createReadyBuilder<TNewData, TNewMeta, TTags>({
+        tags: state.tags,
+        permission: state.permission,
+      });
+    },
+    tags<const TNewTags extends string[]>(...tags: TNewTags) {
+      return createReadyBuilder<TData, TMeta, TNewTags>({
+        tags,
+        permission: state.permission,
+        transform: state.transform,
+        visibleWhen: state.visibleWhen as CommandCondition<TData, TMeta> | undefined,
+        disabledWhen: state.disabledWhen as CommandCondition<TData, TMeta> | undefined,
+      });
+    },
     permission(permission: Permission) {
-      return createReadyBuilder<TSchema, TMeta>({ ...state, permission });
+      return createReadyBuilder<TData, TMeta, TTags>({ ...state, permission });
+    },
+    transform<TNewData>(fn: (data: TData) => TNewData) {
+      // TInput freezes to the current TData; TData advances to TNewData.
+      // The returned builder is typed ReadyCommandBuilder<TNewData, TMeta, TTags, TData>
+      // but createReadyBuilder only tracks TData (output); TInput is enforced via the cast.
+      return createReadyBuilder<TNewData, TMeta, TTags>({
+        tags: state.tags,
+        permission: state.permission,
+        transform: fn as (data: unknown) => unknown,
+      }) as unknown as ReadyCommandBuilder<TNewData, TMeta, TTags, TData>;
     },
-    visibleWhen(condition: CommandCondition<TSchema, TMeta>) {
-      return createReadyBuilder<TSchema, TMeta>({ ...state, visibleWhen: condition });
+    visibleWhen(condition: CommandCondition<TData, TMeta>) {
+      return createReadyBuilder<TData, TMeta, TTags>({ ...state, visibleWhen: condition });
     },
-    disabledWhen(condition: CommandCondition<TSchema, TMeta>) {
-      return createReadyBuilder<TSchema, TMeta>({ ...state, disabledWhen: condition });
+    disabledWhen(condition: CommandCondition<TData, TMeta>) {
+      return createReadyBuilder<TData, TMeta, TTags>({ ...state, disabledWhen: condition });
     },
-    render(render: CommandRender<TSchema, TMeta>) {
+    render(render: CommandRender<TData, TMeta>) {
+      // The transform field is stored as (data: unknown) => unknown in ReadyState but
+      // CommandDef.transform is typed as (data: TInput) => TData. The cast bridges the gap;
+      // runtime correctness is guaranteed by the builder's type constraints.
       return {
+        tags: state.tags,
+        transform: state.transform,
         permission: state.permission,
-        schema: state.schema,
         visibleWhen: state.visibleWhen,
         disabledWhen: state.disabledWhen,
         render,
-      };
+      } as unknown as CommandDef<TData, TMeta, TTags, TData>;
     },
-  };
+  } as ReadyCommandBuilder<TData, TMeta, TTags, TData>;
 }
 
 export function createCommandBuilder<TMeta = object>(): InitialCommandBuilder<TMeta> {