@djangocfg/ui-core 2.1.320 → 2.1.321

package/src/components/select/README.md

@@ -23,6 +23,8 @@ components/select/
 
 Low-level primitives with icon and badge support.
 
+> **Empty-string values are allowed.** Radix forbids `<Select.Item value="" />` (it reserves `''` for "cleared selection"). Our `Select` wrapper substitutes a sentinel (`'__empty__'`) internally for both the controlled value and item values, so consumers can use `''` as a normal enum value (e.g. for "none"). The sentinel never leaks into `onValueChange` — it's an implementation detail.
+
 ```tsx
 import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@djangocfg/ui-core';
 

package/src/components/select/select.tsx

@@ -8,7 +8,42 @@ import * as SelectPrimitive from '@radix-ui/react-select';
 import { cn } from '../../lib/utils';
 import { Badge } from '../data/badge';
 
-const Select = SelectPrimitive.Root
+/**
+ * Radix `<Select.Item value="" />` is reserved (it's how Radix represents
+ * "cleared selection"), so passing an empty string at the consumer level
+ * throws. This wrapper transparently substitutes empty strings with a
+ * sentinel for the Radix layer and unwraps it again on `onValueChange`,
+ * letting consumers use `''` for "none" without inventing their own marker.
+ *
+ * Applies to `Select` (controlled value/defaultValue/onValueChange) and
+ * `SelectItem` (item value).
+ */
+const EMPTY_SENTINEL = '__empty__';
+const toRadix = (raw: string | undefined): string | undefined => {
+  if (raw === undefined) return undefined;
+  return raw === '' ? EMPTY_SENTINEL : raw;
+};
+const fromRadix = (raw: string): string => (raw === EMPTY_SENTINEL ? '' : raw);
+
+function Select(
+  props: React.ComponentPropsWithoutRef<typeof SelectPrimitive.Root>,
+): React.ReactElement {
+  const { value, defaultValue, onValueChange, ...rest } = props;
+  const handleChange = React.useCallback(
+    (next: string) => {
+      onValueChange?.(fromRadix(next));
+    },
+    [onValueChange],
+  );
+  return (
+    <SelectPrimitive.Root
+      value={toRadix(value)}
+      defaultValue={toRadix(defaultValue)}
+      onValueChange={onValueChange ? handleChange : undefined}
+      {...rest}
+    />
+  );
+}
 
 const SelectGroup = SelectPrimitive.Group
 
@@ -120,14 +155,15 @@ SelectLabel.displayName = SelectPrimitive.Label.displayName
 
 const SelectItem = React.forwardRef<
   React.ElementRef<typeof SelectPrimitive.Item>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item> & { 
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item> & {
     key?: React.Key;
     icon?: React.ComponentType<{ className?: string }>;
     badge?: string | React.ReactNode;
   }
->(({ className, children, icon: Icon, badge, ...props }, ref) => (
+>(({ className, children, icon: Icon, badge, value, ...props }, ref) => (
   <SelectPrimitive.Item
     ref={ref}
+    value={value === '' ? EMPTY_SENTINEL : value}
     className={cn(
       "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
       className

package/src/lib/configurator-schema.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared types for schema-driven configurator UIs in the djangocfg monorepo.
+ *
+ * This is **our** mini-spec — a Draft 7-shaped subset that any package can use
+ * to describe a configurator without taking a runtime dependency on RJSF or
+ * any other form framework. `@djangocfg/ui-tools`'s `<JsonSchemaForm>` accepts
+ * these types directly (it casts internally to RJSF's own types).
+ *
+ * Use this when you ship a configurator schema from a non-form package
+ * (e.g. `@djangocfg/layouts/configurator`) so the package stays decoupled
+ * from any concrete form framework.
+ *
+ * Naming choice: not `JsonSchema` (would clash with the broader Draft 7 spec
+ * and other community types). `CustomJsonSchema7` makes the scope explicit:
+ * this is for sidebar / settings configurators, not arbitrary JSON validation.
+ */
+
+/** Primitive JSON Schema types we cover. */
+export type CustomJsonSchema7Type =
+  | 'object'
+  | 'array'
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'null';
+
+/** A Draft 7-shaped JSON Schema descriptor — sufficient for configurator UIs. */
+export interface CustomJsonSchema7 {
+  type?: CustomJsonSchema7Type;
+  title?: string;
+  description?: string;
+  default?: unknown;
+  enum?: readonly (string | number | boolean | null)[];
+  /** Whitelist of property keys that must be set (objects only). */
+  required?: readonly string[];
+  /** Object child schemas. */
+  properties?: Record<string, CustomJsonSchema7>;
+  /** Array item schema. */
+  items?: CustomJsonSchema7;
+  /** Numeric bounds. */
+  minimum?: number;
+  maximum?: number;
+  /** String / array bounds. */
+  minLength?: number;
+  maxLength?: number;
+  /** String format (e.g. `'email'`, `'uri'`). */
+  format?: string;
+  /** Free-form extras kept as-is — let downstream form frameworks read them. */
+  [key: string]: unknown;
+}
+
+/**
+ * Conditional-disable rule attached to a field via `'ui:disabledWhen'` in
+ * `CustomJsonUiSchema7`. Evaluated against the form's current data by the
+ * runtime (`@djangocfg/ui-tools`'s `evaluateDisabledWhen`).
+ */
+export type CustomJsonUiDisabledWhenRule =
+  | { path: string; eq: unknown }
+  | { path: string; notEq: unknown }
+  | { path: string; in: readonly unknown[] }
+  | { path: string; notIn: readonly unknown[] }
+  | { path: string; truthy: true }
+  | { path: string; falsy: true };
+
+/**
+ * Sub-group descriptor used by `'ui:groups'` on an object's uiSchema. Splits
+ * the object into collapsible sub-sections without restructuring the schema.
+ */
+export interface CustomJsonUiGroup {
+  /** Section title shown on the trigger row. */
+  title: string;
+  /** Property keys to include in this group. */
+  fields: readonly string[];
+  /** Initial open state. Default `true`. */
+  defaultOpen?: boolean;
+}
+
+/**
+ * Per-field UI hints that travel alongside `CustomJsonSchema7`. Mirrors the
+ * subset of RJSF `uiSchema` we use, plus our own `ui:disabledWhen`
+ * / `ui:groups` extensions.
+ */
+export interface CustomJsonUiSchema7 {
+  /** Override the widget for this field (`'select'`, `'switch'`, `'slider'`, `'textarea'`, …). */
+  'ui:widget'?: string;
+  /** Free-form widget options (e.g. `{ unit: 'px', step: 2 }` for slider). */
+  'ui:options'?: Record<string, unknown>;
+  /** Description override; in compact density the value moves into the label tooltip. */
+  'ui:description'?: string;
+  /** Wrap this object body in a single Collapsible card. */
+  'ui:collapsible'?: boolean;
+  /** Initial collapsed state when `ui:collapsible`. Default `false` (open). */
+  'ui:collapsed'?: boolean;
+  /** Grid column count for an object body (1, 2, 3 …). */
+  'ui:grid'?: number;
+  /** Extra wrapper class. */
+  'ui:className'?: string;
+  /** Split an object into collapsible sub-sections. */
+  'ui:groups'?: readonly CustomJsonUiGroup[];
+  /** Declarative conditional disable. */
+  'ui:disabledWhen'?: CustomJsonUiDisabledWhenRule;
+  /** Per-property nested uiSchema (keys mirror `properties` keys on the schema). */
+  [key: string]: unknown;
+}

package/src/lib/index.ts

@@ -3,3 +3,10 @@ export * from "./logger";
 export * from "./dialog-service";
 export * from "./env";
 export * from "./persist";
+export type {
+  CustomJsonSchema7,
+  CustomJsonSchema7Type,
+  CustomJsonUiSchema7,
+  CustomJsonUiGroup,
+  CustomJsonUiDisabledWhenRule,
+} from "./configurator-schema";