@djangocfg/ui-tools 2.1.320 → 2.1.322

package/src/tools/JsonForm/JsonForm.story.tsx

@@ -1,10 +1,12 @@
 import { defineStory, useSelect, useBoolean } from '@djangocfg/playground';
+import { useState } from 'react';
 import { JsonSchemaForm } from './index';
 
 export default defineStory({
   title: 'Tools/Json Schema Form',
   component: JsonSchemaForm,
-  description: 'Dynamic form generator from JSON Schema using react-jsonschema-form.',
+  description:
+    'Dynamic form generator from JSON Schema using react-jsonschema-form. Supports density (compact), conditional disable via `ui:disabledWhen`, and collapsible sub-sections via `ui:groups`.',
 });
 
 const SCHEMAS = {
@@ -77,6 +79,13 @@ export const Interactive = () => {
     description: 'Select form schema',
   });
 
+  const [density] = useSelect('density', {
+    options: ['comfortable', 'compact'] as const,
+    defaultValue: 'comfortable',
+    label: 'Density',
+    description: '`compact` shrinks rows and moves description into label tooltip.',
+  });
+
   const [liveValidate] = useBoolean('liveValidate', {
     defaultValue: false,
     label: 'Live Validate',
@@ -91,6 +100,7 @@ export const Interactive = () => {
         schema={config.schema}
         uiSchema={config.uiSchema}
         liveValidate={liveValidate}
+        density={density}
         onSubmit={(data) => console.log('Submitted:', data.formData)}
       />
     </div>
@@ -132,3 +142,209 @@ export const WithDefaultValues = () => (
     />
   </div>
 );
+
+/**
+ * Compact density — shrinks rows, moves description into a tooltip on the
+ * label. Pair with `ui:groups` for dense sidebar / playground configurators.
+ */
+export const Compact = () => (
+  <div className="max-w-md">
+    <JsonSchemaForm
+      schema={SCHEMAS.simple.schema}
+      density="compact"
+      showSubmitButton={false}
+      onSubmit={(data) => console.log('Submitted:', data.formData)}
+    />
+  </div>
+);
+
+/**
+ * `ui:disabledWhen` greys out a field based on another field's value.
+ * Here `phone` is disabled until `subscribe` is checked, and `email` is
+ * disabled when `firstName` is empty.
+ */
+export const ConditionalDisable = () => {
+  const [data, setData] = useState<Record<string, unknown>>({
+    firstName: '',
+    subscribe: false,
+  });
+  return (
+    <div className="max-w-lg">
+      <JsonSchemaForm
+        schema={SCHEMAS.contact.schema}
+        uiSchema={{
+          ...SCHEMAS.contact.uiSchema,
+          email: {
+            'ui:disabledWhen': { path: 'firstName', falsy: true },
+          },
+          phone: {
+            'ui:disabledWhen': { path: 'subscribe', falsy: true },
+          },
+          subscribe: { 'ui:widget': 'switch' },
+        }}
+        formData={data}
+        onChange={(e) => setData(e.formData ?? {})}
+        showSubmitButton={false}
+      />
+      <pre className="mt-3 text-[11px] text-muted-foreground">
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    </div>
+  );
+};
+
+/**
+ * `ui:groups` splits a flat object into collapsible sub-sections without
+ * restructuring the schema. Fields not listed in any group render flat above
+ * the groups.
+ */
+export const CollapsibleGroups = () => (
+  <div className="max-w-lg">
+    <JsonSchemaForm
+      schema={{
+        type: 'object',
+        properties: {
+          identity: { type: 'string', title: 'Display name' },
+          firstName: { type: 'string', title: 'First name' },
+          lastName: { type: 'string', title: 'Last name' },
+          email: { type: 'string', title: 'Email', format: 'email' },
+          phone: { type: 'string', title: 'Phone' },
+          newsletter: { type: 'boolean', title: 'Newsletter' },
+          marketing: { type: 'boolean', title: 'Marketing emails' },
+          tracking: { type: 'boolean', title: 'Usage analytics' },
+        },
+      }}
+      uiSchema={{
+        'ui:groups': [
+          {
+            title: 'Personal',
+            fields: ['firstName', 'lastName'],
+            defaultOpen: true,
+          },
+          { title: 'Contact', fields: ['email', 'phone'], defaultOpen: false },
+          {
+            title: 'Preferences',
+            fields: ['newsletter', 'marketing', 'tracking'],
+            defaultOpen: false,
+          },
+        ],
+        newsletter: { 'ui:widget': 'switch' },
+        marketing: { 'ui:widget': 'switch' },
+        tracking: { 'ui:widget': 'switch' },
+      }}
+      density="compact"
+      showSubmitButton={false}
+      onChange={(e) => console.log('changed:', e.formData)}
+    />
+  </div>
+);
+
+/**
+ * Empty-string enum values are now allowed — Radix `<Select.Item value="" />`
+ * is reserved, so the ui-core `Select` wrapper substitutes a sentinel
+ * internally. From the schema's perspective `''` is just another option.
+ */
+export const EmptyStringSelect = () => {
+  const [data, setData] = useState<Record<string, unknown>>({ plan: '' });
+  return (
+    <div className="max-w-md">
+      <JsonSchemaForm
+        schema={{
+          type: 'object',
+          properties: {
+            plan: {
+              type: 'string',
+              title: 'Plan',
+              enum: ['', 'Free', 'Pro', 'Max', 'Enterprise'],
+              description: 'An empty string is a valid enum value here.',
+            },
+          },
+        }}
+        uiSchema={{
+          plan: {
+            'ui:enumNames': ['— none —', 'Free', 'Pro', 'Max', 'Enterprise'],
+          },
+        }}
+        formData={data}
+        onChange={(e) => setData(e.formData ?? {})}
+        showSubmitButton={false}
+      />
+      <pre className="mt-3 text-[11px] text-muted-foreground">
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    </div>
+  );
+};
+
+/**
+ * Live demo of all extensions wired together — compact density, collapsible
+ * groups, conditional disable, slider with unit. Mirrors what the layouts
+ * playground sidebar uses.
+ */
+export const PlaygroundStyle = () => {
+  const [data, setData] = useState<Record<string, unknown>>({
+    shell: { variant: 'boxed', inset: 12, radius: '2xl', border: true },
+    sidebar: {
+      density: 'default',
+      activeIndicator: 'background',
+      collapsibleGroups: false,
+    },
+  });
+  return (
+    <div className="max-w-md">
+      <JsonSchemaForm
+        schema={{
+          type: 'object',
+          properties: {
+            shell: {
+              type: 'object',
+              title: 'Shell',
+              properties: {
+                variant: { type: 'string', title: 'Variant', enum: ['full-bleed', 'boxed'] },
+                inset: { type: 'integer', title: 'Inset', minimum: 0, maximum: 32 },
+                radius: { type: 'string', title: 'Radius', enum: ['sm', 'md', 'lg', 'xl', '2xl', '3xl'] },
+                border: { type: 'boolean', title: 'Border' },
+              },
+            },
+            sidebar: {
+              type: 'object',
+              title: 'Sidebar',
+              properties: {
+                density: { type: 'string', title: 'Density', enum: ['sparse', 'default', 'dense'] },
+                activeIndicator: {
+                  type: 'string',
+                  title: 'Active indicator',
+                  enum: ['background', 'rail', 'both'],
+                },
+                collapsibleGroups: { type: 'boolean', title: 'Collapsible groups' },
+              },
+            },
+          },
+        }}
+        uiSchema={{
+          shell: {
+            'ui:collapsible': true,
+            inset: {
+              'ui:widget': 'slider',
+              'ui:options': { unit: 'px', step: 2, showInput: false },
+              'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+            },
+            radius: { 'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' } },
+            border: {
+              'ui:widget': 'switch',
+              'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+            },
+          },
+          sidebar: {
+            'ui:collapsible': true,
+            collapsibleGroups: { 'ui:widget': 'switch' },
+          },
+        }}
+        formData={data}
+        onChange={(e) => setData(e.formData ?? {})}
+        density="compact"
+        showSubmitButton={false}
+      />
+    </div>
+  );
+};

package/src/tools/JsonForm/JsonSchemaForm.tsx

@@ -7,14 +7,14 @@ import React, { useCallback, useMemo } from 'react';
 
 import { Alert, AlertDescription, Button } from '@djangocfg/ui-core/components';
 import Form from '@rjsf/core';
-import { RegistryWidgetsType } from '@rjsf/utils';
+import { RegistryWidgetsType, UiSchema } from '@rjsf/utils';
 import validator from '@rjsf/validator-ajv8';
 
 import {
     ArrayFieldItemTemplate, ArrayFieldTemplate, BaseInputTemplate, ErrorListTemplate, FieldTemplate,
     ObjectFieldTemplate
 } from './templates';
-import { JsonSchemaFormProps } from './types';
+import { JsonFormContext, JsonSchemaFormProps } from './types';
 import { normalizeFormData, validateSchema } from './utils';
 import {
     CheckboxWidget, ColorWidget, NumberWidget, SelectWidget, SliderWidget, SwitchWidget, TextWidget
@@ -60,6 +60,8 @@ export function JsonSchemaForm<T = any>(props: JsonSchemaFormProps<T>) {
     className,
     showSubmitButton = true,
     submitButtonText = 'Submit',
+    density = 'comfortable',
+    formContext: callerFormContext,
     ...restProps
   } = props;
 
@@ -167,15 +169,24 @@ export function JsonSchemaForm<T = any>(props: JsonSchemaFormProps<T>) {
     );
   }
 
+  // formContext threads the latest formData + density into widgets/templates so
+  // they can react to global form state (conditional disable, density CSS).
+  const formContext = useMemo<JsonFormContext & Record<string, unknown>>(() => ({
+    ...(callerFormContext as object | undefined),
+    density,
+    formData: normalizedFormData,
+  }), [callerFormContext, density, normalizedFormData]);
+
   return (
-    <div className={className}>
+    <div className={className} data-jsonform-density={density}>
       <Form
         schema={validatedSchema}
-        uiSchema={uiSchema}
+        uiSchema={uiSchema as UiSchema | undefined}
         formData={normalizedFormData}
         validator={validator}
         widgets={widgets}
         templates={templates}
+        formContext={formContext}
         onSubmit={handleSubmit}
         onChange={handleChange}
         onError={handleError}

package/src/tools/JsonForm/README.md

@@ -0,0 +1,268 @@
+# JsonForm
+
+Schema-driven forms on top of [react-jsonschema-form](https://github.com/rjsf-team/react-jsonschema-form) (RJSF) with `@djangocfg/ui` widgets, AJV8 validation, and a few custom extensions for compact playground-style UIs.
+
+```tsx
+import { JsonSchemaForm } from '@djangocfg/ui-tools/json-form';
+// or, for code-splitting:
+import { LazyJsonSchemaForm } from '@djangocfg/ui-tools';
+
+const schema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', title: 'Name' },
+    age:  { type: 'integer', title: 'Age', minimum: 0 },
+  },
+};
+
+<JsonSchemaForm schema={schema} onSubmit={(e) => console.log(e.formData)} />
+```
+
+---
+
+## Components
+
+| Export | Use |
+|---|---|
+| `JsonSchemaForm` | Direct (synchronous) form. |
+| `LazyJsonSchemaForm` | Same API, lazy-loaded with a `<CardLoadingFallback>` (RJSF is ~300KB). |
+
+Both accept the same `JsonSchemaFormProps`:
+
+| Prop | Type | Notes |
+|---|---|---|
+| `schema` | `RJSFSchema` | Required. JSON Schema 7. |
+| `uiSchema` | `UiSchema` | Optional. Widget overrides + custom extensions (see below). |
+| `formData` | `T` | Initial / controlled data. |
+| `onChange` | `(e) => void` | Live changes. |
+| `onSubmit` | `(e) => void` | Submit (enter or button). |
+| `onError` | `(errors) => void` | Validation errors. |
+| `density` | `'comfortable' \| 'compact'` | Default `'comfortable'`. See **Density** below. |
+| `liveValidate` | `boolean` | Default `false`. |
+| `disabled` / `readonly` | `boolean` | Form-wide. |
+| `showSubmitButton` | `boolean` | Default `true`. |
+| `submitButtonText` | `string` | Default `'Submit'`. |
+| `showErrorList` | `false \| 'top' \| 'bottom'` | Default `'top'`. |
+| `className` | `string` | Wrapper class. |
+
+---
+
+## Built-in widgets
+
+Mapped via `widgets={{ ... }}` and registered under both PascalCase and lowercase aliases — use whichever matches your `uiSchema`.
+
+| `ui:widget` | Widget | Built on |
+|---|---|---|
+| `text` | `TextWidget` | `<Input />` |
+| `number` | `NumberWidget` | `<Input type="number" />` |
+| `checkbox` | `CheckboxWidget` | `<Checkbox />` |
+| `switch` | `SwitchWidget` | `<Switch />` |
+| `select` | `SelectWidget` | `<Select />` (auto-falls back to `<input type="text">` when no enum) |
+| `slider` / `range` | `SliderWidget` | `<Slider />` (+ optional inline numeric input, supports unit suffix) |
+| `color` | `ColorWidget` | Native colour picker. |
+
+### Slider options
+
+```ts
+'ui:widget': 'slider',
+'ui:options': {
+  unit: 'px',        // appended to the displayed value: "12px"
+  step: 2,
+  showInput: false,  // hide the editable text input next to the slider
+}
+```
+
+---
+
+## Templates
+
+Custom RJSF templates live in `./templates/`:
+
+- `FieldTemplate` — label + body + errors. Honors `density`.
+- `ObjectFieldTemplate` — object body. Supports `ui:collapsible`, `ui:grid`, `ui:className`, and **`ui:groups`** (see below).
+- `ArrayFieldTemplate`, `ArrayFieldItemTemplate` — array editing.
+- `ErrorListTemplate` — top/bottom error block.
+- `BaseInputTemplate` — fallback input wrapper.
+
+---
+
+## Custom extensions
+
+These are extra `uiSchema` keys this fork understands on top of stock RJSF.
+
+### `density`
+
+Form-wide compact mode. Drives label sizing, row spacing, and tooltip placement.
+
+```tsx
+<JsonSchemaForm density="compact" ... />
+```
+
+In compact mode:
+- Labels: 10px uppercase muted, no description paragraph
+- Description (`schema.description` or `ui:description`) becomes a `title=` tooltip on the label
+- Tighter row spacing (`space-y-1` vs `space-y-2`)
+- Slimmer select trigger (`h-7`) and inputs
+
+Use this for sidebars, settings drawers, dense playground configurators.
+
+### `ui:disabledWhen`
+
+Declarative conditional disable, evaluated against the current `formData`. Avoids the JSON Schema `dependencies` boilerplate when you just want to grey a field out.
+
+```ts
+const uiSchema = {
+  shell: {
+    inset: {
+      'ui:widget': 'slider',
+      'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+    },
+  },
+};
+```
+
+Supported rule shapes:
+
+| Shape | Disabled when |
+|---|---|
+| `{ path, eq: value }` | field at `path` equals `value` |
+| `{ path, notEq: value }` | field at `path` does not equal `value` |
+| `{ path, in: [...] }` | field is in array |
+| `{ path, notIn: [...] }` | field is not in array |
+| `{ path, truthy: true }` | field is truthy |
+| `{ path, falsy: true }` | field is falsy / empty / `false` / `0` |
+
+`path` is dot-separated against `formData` root (e.g. `'shell.variant'`, `'navbar.controls.showThemeSwitcher'`).
+
+The runtime `evaluateDisabledWhen(rule, formData)` is exported for tests / reuse.
+
+### `ui:groups` (in `ObjectFieldTemplate`)
+
+Splits a flat object into collapsible sub-sections without restructuring the schema.
+
+```ts
+sidebar: {
+  'ui:groups': [
+    { title: 'Density', fields: ['density'], defaultOpen: true },
+    { title: 'Slots',   fields: ['showMenuStart', 'showMenuEnd'], defaultOpen: false },
+    { title: 'Visual',  fields: ['activeIndicator', 'groupLabelStyle'] },
+  ],
+}
+```
+
+Fields not listed in any group render flat above the groups. Each group is a `<Collapsible>` with a chevron-right header.
+
+### `ui:collapsible` / `ui:collapsed` (existing)
+
+Wraps the entire object in a single collapsible card. Independent of `ui:groups` — use one or the other on a given object.
+
+### `ui:grid` (existing)
+
+`'ui:grid': 2` switches the object body to a 2-column grid (`gap-4`). Default is vertical stack.
+
+---
+
+## Example — playground sidebar
+
+The `apps/demo` layouts playground uses the stack end-to-end:
+
+```ts
+// schema
+const privateSchema: RJSFSchema = {
+  type: 'object',
+  properties: {
+    shell: { type: 'object', properties: { variant: { type: 'string', enum: ['full-bleed', 'boxed'] }, inset: { type: 'integer', minimum: 0, maximum: 32 } } },
+    sidebar: { type: 'object', properties: { /* ... */ } },
+  },
+};
+
+// uiSchema
+const privateUiSchema: UiSchema = {
+  shell: {
+    'ui:collapsible': true,
+    inset: {
+      'ui:widget': 'slider',
+      'ui:options': { unit: 'px', step: 2, showInput: false },
+      'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+    },
+  },
+  sidebar: {
+    'ui:collapsible': true,
+    'ui:groups': [
+      { title: 'Density', fields: ['density'], defaultOpen: true },
+      { title: 'Visual',  fields: ['activeIndicator', 'groupLabelStyle'] },
+    ],
+  },
+};
+
+// component
+<LazyJsonSchemaForm
+  schema={privateSchema}
+  uiSchema={privateUiSchema}
+  formData={config}
+  onChange={(e) => setConfig(e.formData)}
+  density="compact"
+  showSubmitButton={false}
+  liveValidate={false}
+/>
+```
+
+See `apps/demo/.../layouts/sidebar/{private,public}/Sidebar.tsx` for the full integration.
+
+---
+
+## Internals
+
+| File | Role |
+|---|---|
+| `JsonSchemaForm.tsx` | Top-level component. Validates schema, normalises `formData`, threads `formContext = { density, formData }` to widgets/templates. |
+| `widgets/_useWidgetEnv.ts` | Internal hook reading density + `ui:disabledWhen` from `formContext`. Used by `Switch`, `Select`, `Slider`, `Checkbox`. |
+| `templates/ObjectFieldTemplate.tsx` | Implements `ui:collapsible`, `ui:grid`, `ui:groups`. |
+| `templates/FieldTemplate.tsx` | Density-aware label / description / errors layout. |
+| `utils.ts` | `validateSchema`, `normalizeFormData`, `evaluateDisabledWhen`, plus default-merging helpers. |
+
+---
+
+## Re-exported types
+
+For consumers that don't have `@rjsf/utils` as a direct dependency:
+
+```ts
+import type {
+  RJSFSchema,
+  UiSchema,
+  JsonSchemaFormProps,
+  JsonFormDensity,
+  DisabledWhenRule,
+  UiGroup,
+  JsonFormContext,
+} from '@djangocfg/ui-tools';
+```
+
+### Portable schema types (`CustomJson*`)
+
+For packages that **ship a configurator schema** without taking a runtime
+dependency on RJSF — typically library packages like `@djangocfg/layouts/configurator`
+— use the portable types from `@djangocfg/ui-core/lib`:
+
+```ts
+import type {
+  CustomJsonSchema7,
+  CustomJsonSchema7Type,
+  CustomJsonUiSchema7,
+  CustomJsonUiGroup,
+  CustomJsonUiDisabledWhenRule,
+} from '@djangocfg/ui-core/lib';
+
+// also re-exported from `@djangocfg/ui-tools` for convenience.
+```
+
+These are our own Draft 7-shaped subset (not a copy of RJSF's types) and
+`<JsonSchemaForm>` accepts them directly via union with `RJSFSchema`. Library
+packages typing their schemas with `CustomJsonSchema7` stay decoupled from
+the form framework — if RJSF is ever swapped out, these schemas don't need
+to change.
+
+The aliases `DisabledWhenRule` and `UiGroup` exported from `@djangocfg/ui-tools`
+point at `CustomJsonUiDisabledWhenRule` / `CustomJsonUiGroup` respectively
+(kept for back-compat with existing consumers).

package/src/tools/JsonForm/index.ts

@@ -34,7 +34,28 @@
  */
 
 export { JsonSchemaForm } from './JsonSchemaForm';
-export type { JsonSchemaFormProps } from './types';
+export type {
+  JsonSchemaFormProps,
+  JsonFormDensity,
+  DisabledWhenRule,
+  UiGroup,
+  JsonFormContext,
+} from './types';
+export { evaluateDisabledWhen } from './utils';
+
+// Re-export RJSF schema types so consumers don't need to install `@rjsf/utils`
+// directly. Keeps ui-tools the single dependency for schema-driven forms.
+export type { RJSFSchema, UiSchema } from '@rjsf/utils';
+
+// Re-export the portable schema types from ui-core for convenience: most
+// configurator authors only need these (no RJSF coupling).
+export type {
+  CustomJsonSchema7,
+  CustomJsonSchema7Type,
+  CustomJsonUiSchema7,
+  CustomJsonUiGroup,
+  CustomJsonUiDisabledWhenRule,
+} from '@djangocfg/ui-core/lib';
 
 // Export widgets for custom usage
 export * from './widgets';

package/src/tools/JsonForm/templates/FieldTemplate.tsx

@@ -6,6 +6,8 @@ import { Label } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 import { FieldTemplateProps } from '@rjsf/utils';
 
+import type { JsonFormDensity } from '../types';
+
 /**
  * Field template for JSON Schema Form
  * Controls the layout and styling of individual form fields
@@ -25,36 +27,57 @@ export function FieldTemplate(props: FieldTemplateProps) {
     hidden,
     rawErrors,
   } = props;
+  const formContext = (props as { formContext?: { density?: JsonFormDensity } }).formContext;
 
   if (hidden) {
     return <div className="hidden">{children}</div>;
   }
 
   const hasError = rawErrors && rawErrors.length > 0;
+  const density = (formContext?.density as JsonFormDensity | undefined) ?? 'comfortable';
+  const compact = density === 'compact';
+
+  // In compact mode the description is suppressed in the body and forwarded to
+  // the label `title=` tooltip — keeps rows dense without losing context.
+  const descriptionText =
+    typeof description === 'string'
+      ? description
+      : undefined;
+  const labelTitle = compact ? descriptionText : undefined;
+  const showDescription = !compact && Boolean(description);
 
   return (
     <div
-      className={cn('space-y-2', classNames)}
+      className={cn(compact ? 'space-y-1' : 'space-y-2', classNames)}
       style={style}
     >
       {displayLabel && label && (
-        <Label htmlFor={id} className={cn(hasError && 'text-destructive')}>
+        <Label
+          htmlFor={id}
+          className={cn(
+            hasError && 'text-destructive',
+            compact && 'text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/70',
+          )}
+          title={labelTitle}
+        >
           {label}
           {required && <span className="text-destructive ml-1">*</span>}
         </Label>
       )}
 
-      {description && (
+      {showDescription && (
         <div className="text-sm text-muted-foreground">{description}</div>
       )}
 
       <div>{children}</div>
 
       {errors && (
-        <div className="text-sm text-destructive">{errors}</div>
+        <div className={compact ? 'text-xs text-destructive' : 'text-sm text-destructive'}>
+          {errors}
+        </div>
       )}
 
-      {help && (
+      {help && !compact && (
         <div className="text-sm text-muted-foreground">{help}</div>
       )}
     </div>