zod-collection-ui 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Collection Affordance Schema — Core Types
+ *
+ * Defines the vocabulary for declaring what operations a collection of typed items
+ * supports, both at the collection level and per-field level.
+ *
+ * Terminology (following Gibson/Norman affordance theory):
+ * - Affordance: a declared capability (what the system CAN do)
+ * - Signifier: a UI element that communicates an affordance (what the user SEES)
+ * - Collection: a typed, queryable set of items
+ * - Item: a single member of a collection
+ * - Field: a named property of an item's type
+ * - Operation: a concrete action invokable on items/selection/collection
+ */
+/** How a field can be sorted */
+export type SortDirection = 'asc' | 'desc' | 'both' | 'none';
+/** What kind of filter UI is appropriate for a field */
+export type FilterType = 'exact' | 'search' | 'select' | 'multiSelect' | 'range' | 'contains' | 'boolean' | 'fuzzy';
+/** Aggregation functions applicable to a field */
+export type AggregationFn = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'median' | 'uniqueCount';
+/**
+ * Declares what operations are meaningful on a single field of an item.
+ *
+ * Design principle: exclusion-based (OData pattern).
+ * If not specified, defaults are inferred from the Zod type.
+ */
+export interface FieldAffordance {
+    /** Can items be ordered by this field? Default: inferred from type. */
+    sortable?: boolean | SortDirection;
+    /** Can items be narrowed by this field? Default: inferred from type. */
+    filterable?: boolean | FilterType;
+    /** Is this field included in full-text search? Default: true for strings. */
+    searchable?: boolean;
+    /** Can items be grouped by this field's values? Default: true for enums. */
+    groupable?: boolean;
+    /** Aggregate functions applicable to this field. Default: inferred from numeric types. */
+    aggregatable?: boolean | AggregationFn[];
+    /** Is this field returned in responses? Default: true. */
+    readable?: boolean;
+    /** Can this field be modified? Default: inferred from field name/type. */
+    editable?: boolean;
+    /** Can be edited directly in the collection view (click-to-edit)? */
+    inlineEditable?: boolean;
+    /** Required when creating a new item (but not on update)? */
+    requiredOnCreate?: boolean;
+    /** Required when updating an item? */
+    requiredOnUpdate?: boolean;
+    /** Editable on create but read-only on update? */
+    immutableAfterCreate?: boolean;
+    /** Whether this field appears in the collection view. Default: true. */
+    visible?: boolean;
+    /** Explicitly hidden (stronger than visible: false — cannot be toggled by user). */
+    hidden?: boolean;
+    /** Only shown in detail/edit view, never in list/table. */
+    detailOnly?: boolean;
+    /** Appears in compact/summary views. */
+    summaryField?: boolean;
+    /** Default column width in pixels. */
+    columnWidth?: number;
+    /** Minimum column width. */
+    minWidth?: number;
+    /** Maximum column width. */
+    maxWidth?: number;
+    /** Can the user resize this column? Default: true. */
+    resizable?: boolean;
+    /** Pin to left or right edge. */
+    pinned?: 'left' | 'right' | false;
+    /** Position in field/column order (lower = earlier). */
+    order?: number;
+    /** Human-readable label for this field. Default: humanized from key. */
+    title?: string;
+    /** Description/help text for this field. */
+    description?: string;
+    /** Format string or function for display. */
+    displayFormat?: string;
+    /** Map enum values to badge variant names. */
+    badge?: Record<string, string>;
+    /** Make the value copyable with a clipboard button. */
+    copyable?: boolean;
+    /** Max characters before truncation. */
+    truncate?: number;
+    /** Show full value on hover when truncated. */
+    tooltip?: boolean;
+    /** Override the default edit widget type. */
+    editWidget?: string;
+    /** Placeholder text for edit widget. */
+    editPlaceholder?: string;
+    /** Help text shown below edit widget. */
+    editHelp?: string;
+}
+export interface PaginationConfig {
+    defaultPageSize?: number;
+    pageSizeOptions?: number[];
+    style?: 'pages' | 'loadMore' | 'infinite';
+    serverSide?: boolean;
+}
+export interface SearchConfig {
+    debounce?: number;
+    minChars?: number;
+    highlight?: boolean;
+    placeholder?: string;
+}
+export interface MultiSortConfig {
+    maxColumns?: number;
+}
+export interface GroupByConfig {
+    defaultField?: string;
+    collapsible?: boolean;
+    defaultState?: 'collapsed' | 'expanded';
+}
+export interface FilterPreset {
+    name: string;
+    label: string;
+    filters: Record<string, unknown>;
+    icon?: string;
+}
+export type ViewMode = 'table' | 'grid' | 'list' | 'kanban';
+/**
+ * Declares what operations the collection as a whole supports.
+ *
+ * Design principle: opt-in for operations (create, delete, export),
+ * opt-out for query capabilities (filtering, sorting default to true).
+ */
+export interface CollectionAffordances {
+    create?: boolean;
+    read?: boolean;
+    update?: boolean;
+    delete?: boolean;
+    bulkDelete?: boolean;
+    /** true = all editable fields, string[] = specific fields */
+    bulkEdit?: boolean | string[];
+    bulkArchive?: boolean;
+    search?: boolean | SearchConfig;
+    pagination?: boolean | PaginationConfig;
+    defaultSort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    multiSort?: boolean | MultiSortConfig;
+    filterPanel?: boolean;
+    filterPresets?: FilterPreset[];
+    savedFilters?: boolean;
+    groupBy?: boolean | GroupByConfig;
+    defaultView?: ViewMode;
+    views?: ViewMode[];
+    savedViews?: boolean;
+    export?: boolean | string[];
+    import?: boolean | string[];
+    selectable?: boolean | 'single' | 'multi';
+    refresh?: boolean;
+    autoRefresh?: number;
+    columnVisibility?: boolean;
+    columnOrder?: boolean;
+    columnResize?: boolean;
+    columnPin?: boolean;
+    reorder?: boolean;
+    undo?: boolean;
+}
+export type OperationScope = 'item' | 'selection' | 'collection';
+export interface OperationConfirmation {
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    variant?: 'default' | 'destructive';
+}
+export interface OperationDefinition<TParams = unknown> {
+    /** Unique identifier for this operation. */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** What the operation acts on. */
+    scope: OperationScope;
+    /** Icon name (from icon library). */
+    icon?: string;
+    /** Visual style. */
+    variant?: 'default' | 'destructive' | 'secondary' | 'ghost';
+    /** Confirmation dialog before execution. */
+    confirm?: boolean | OperationConfirmation;
+    /** Keyboard shortcut (e.g., "ctrl+d", "delete"). */
+    keyboardShortcut?: string;
+}
+export interface CollectionConfig<TShape extends Record<string, unknown> = Record<string, unknown>> {
+    /** Collection-level affordances. */
+    affordances?: CollectionAffordances;
+    /** Per-field affordance overrides (merged with Zod .meta()). */
+    fields?: Partial<Record<keyof TShape, Partial<FieldAffordance>>>;
+    /** Custom operations beyond CRUD. */
+    operations?: OperationDefinition[];
+    /** Which field uniquely identifies items. Default: 'id'. */
+    idField?: string;
+    /** Which field is the human-readable label. Default: first string field. */
+    labelField?: string;
+}
+export interface ResolvedFieldAffordance extends Required<Pick<FieldAffordance, 'sortable' | 'filterable' | 'searchable' | 'groupable' | 'editable' | 'visible'>> {
+    title: string;
+    zodType: string;
+    zodDef: unknown;
+    [key: string]: unknown;
+}
+export interface ResolvedCollectionAffordances extends Required<Pick<CollectionAffordances, 'create' | 'read' | 'update' | 'delete' | 'selectable'>> {
+    search: false | SearchConfig;
+    pagination: false | Required<PaginationConfig>;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Collection Affordance Schema — Core Types
+ *
+ * Defines the vocabulary for declaring what operations a collection of typed items
+ * supports, both at the collection level and per-field level.
+ *
+ * Terminology (following Gibson/Norman affordance theory):
+ * - Affordance: a declared capability (what the system CAN do)
+ * - Signifier: a UI element that communicates an affordance (what the user SEES)
+ * - Collection: a typed, queryable set of items
+ * - Item: a single member of a collection
+ * - Field: a named property of an item's type
+ * - Operation: a concrete action invokable on items/selection/collection
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "zod-collection-ui",
+  "version": "0.0.1",
+  "description": "Declare once, render anywhere. Schema-driven collection UIs from Zod — auto-generated table columns, form fields, filters, state, and data providers.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "example:basic": "tsx examples/01-basic-usage.ts",
+    "example:ecommerce": "tsx examples/02-ecommerce-catalog.ts",
+    "example:tasks": "tsx examples/03-task-tracker.ts",
+    "example:zero": "tsx examples/04-zero-config.ts"
+  },
+  "keywords": [
+    "zod",
+    "schema",
+    "ui",
+    "collection",
+    "table",
+    "form",
+    "filter",
+    "tanstack",
+    "headless",
+    "affordance",
+    "crud",
+    "schema-driven",
+    "declarative",
+    "code-generation"
+  ],
+  "author": "Thor Whalen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thorwhalen/zod-collection-ui"
+  },
+  "homepage": "https://github.com/thorwhalen/zod-collection-ui#readme",
+  "bugs": {
+    "url": "https://github.com/thorwhalen/zod-collection-ui/issues"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.0.0"
+  }
+}