@showwhat/configurator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gerald Yeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @showwhat/configurator
+
+A reusable React component library for visually editing showwhat feature flag definitions. Provides a complete rule-builder UI — bring your own store and persistence.
+
+## Installation
+
+```bash
+npm install @showwhat/configurator
+```
+
+Peer dependencies: React 19, React DOM 19.
+
+## Quick start
+
+```tsx
+import { Configurator } from "@showwhat/configurator";
+import "@showwhat/configurator/styles.css";
+
+function App() {
+  return <Configurator store={myStore} />;
+}
+```
+
+## Features
+
+- Visual rule builder for all built-in condition types
+- Drag-and-drop variation reordering
+- Nested AND/OR condition groups
+- Condition simulator and JSON context preview
+- Store-agnostic — bring your own state management and persistence
+- Exports individual components for custom layouts
+- shadcn-based UI primitives included
+- Tailwind CSS v4 with customisable theme tokens
+
+## Documentation
+
+- [Configurator](https://showwhat.yeojz.dev/docs/configurator) — store interfaces, components, hooks, styling, and examples

package/dist/index.d.ts

@@ -0,0 +1,332 @@
+import { Condition, Definition, Definitions, Variation, Presets, ConditionEvaluator, Resolution } from 'showwhat';
+import { ClassValue } from 'clsx';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import * as React$1 from 'react';
+import React__default, { Component, ReactNode, ErrorInfo, ComponentType } from 'react';
+import { VariantProps } from 'class-variance-authority';
+import { Select as Select$1, Separator as Separator$1, ScrollArea as ScrollArea$1, Dialog as Dialog$1, DropdownMenu as DropdownMenu$1, Label as Label$1, Switch as Switch$1, Popover as Popover$1, Tabs as Tabs$1 } from 'radix-ui';
+
+type DefinitionListProps = {
+    definitions: Definitions;
+    selectedKey: string | null;
+    validationErrors?: Record<string, unknown[]>;
+    dirtyKeys?: string[];
+    onSelect: (key: string) => void;
+    onAdd: (key: string) => void | Promise<void>;
+    onRemove: (key: string) => void;
+};
+type DefinitionListItemProps = {
+    definitionKey: string;
+    variationCount: number;
+    isActive: boolean;
+    hasErrors: boolean;
+    isSelected: boolean;
+    isDirty?: boolean;
+    onSelect: () => void;
+    onRemove: () => void;
+};
+type DefinitionEditorProps = {
+    definitionKey: string;
+    definition: Definition;
+    validationErrors?: ValidationIssueDisplay[];
+    isDirty?: boolean;
+    isPending?: boolean;
+    onUpdate: (definition: Definition) => void;
+    onRename: (newKey: string) => void | Promise<void>;
+    onSave?: () => void;
+    onDiscard?: () => void;
+};
+type VariationListProps = {
+    variations: Variation[];
+    validationErrors?: ValidationIssueDisplay[];
+    onChange: (variations: Variation[]) => void;
+};
+type VariationCardProps = {
+    variation: Variation;
+    index: number;
+    validationErrors?: ValidationIssueDisplay[];
+    onChange: (variation: Variation) => void;
+    onRemove: () => void;
+    dragHandleProps?: Record<string, unknown>;
+};
+type ConditionBuilderProps = {
+    conditions: Condition[];
+    onChange: (conditions: Condition[]) => void;
+    validationErrors?: ValidationIssueDisplay[];
+};
+type ConditionBlockProps = {
+    condition: Condition;
+    onChange: (condition: Condition) => void;
+    onRemove: () => void;
+    onMoveUp?: () => void;
+    onMoveDown?: () => void;
+    depth?: number;
+    errors?: ValidationIssueDisplay[];
+};
+type ConditionGroupProps = {
+    type: "and" | "or";
+    conditions: Condition[];
+    onChange: (conditions: Condition[]) => void;
+    onRemove: () => void;
+    onMoveUp?: () => void;
+    onMoveDown?: () => void;
+    depth?: number;
+    errors?: ValidationIssueDisplay[];
+};
+type ConditionValueEditorProps = {
+    condition: Condition;
+    onChange: (condition: Condition) => void;
+};
+type ValueInputProps = {
+    value: unknown;
+    onChange: (value: unknown) => void;
+    placeholder?: string;
+};
+type DateTimeInputProps = {
+    value: string;
+    onChange: (value: string) => void;
+};
+type ValidationIssueDisplay = {
+    path: (string | number)[];
+    message: string;
+};
+type ValidationMessageProps = {
+    errors?: ValidationIssueDisplay[];
+};
+type ThemeToggleProps = {
+    theme: "light" | "dark" | "system";
+    onToggle: (theme: "light" | "dark" | "system") => void;
+};
+
+declare function cn(...inputs: ClassValue[]): string;
+
+declare const AUTO_ID_PREFIX = "_tmp:";
+declare function isAutoId(id: string | undefined): boolean;
+declare function stripAutoIds(definitions: Definitions): Definitions;
+
+interface ConditionTypeMeta {
+    type: string;
+    label: string;
+    description: string;
+    defaults: Record<string, unknown>;
+}
+declare const BUILTIN_CONDITION_TYPES: ConditionTypeMeta[];
+declare const CONDITION_TYPE_MAP: Map<string, ConditionTypeMeta>;
+declare function getConditionMeta(type: string): ConditionTypeMeta | undefined;
+
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost" | null | undefined;
+    size?: "sm" | "default" | "xs" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ref, ...props }: React__default.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function Input({ className, type, ...props }: React__default.ComponentProps<"input">): react_jsx_runtime.JSX.Element;
+
+declare function Select({ ...props }: React__default.ComponentProps<typeof Select$1.Root>): react_jsx_runtime.JSX.Element;
+declare function SelectGroup({ ...props }: React__default.ComponentProps<typeof Select$1.Group>): react_jsx_runtime.JSX.Element;
+declare function SelectValue({ ...props }: React__default.ComponentProps<typeof Select$1.Value>): react_jsx_runtime.JSX.Element;
+declare function SelectTrigger({ className, size, children, ...props }: React__default.ComponentProps<typeof Select$1.Trigger> & {
+    size?: "sm" | "default";
+}): react_jsx_runtime.JSX.Element;
+declare function SelectContent({ className, children, position, align, ...props }: React__default.ComponentProps<typeof Select$1.Content>): react_jsx_runtime.JSX.Element;
+declare function SelectLabel({ className, ...props }: React__default.ComponentProps<typeof Select$1.Label>): react_jsx_runtime.JSX.Element;
+declare function SelectItem({ className, children, ...props }: React__default.ComponentProps<typeof Select$1.Item>): react_jsx_runtime.JSX.Element;
+declare function SelectSeparator({ className, ...props }: React__default.ComponentProps<typeof Select$1.Separator>): react_jsx_runtime.JSX.Element;
+
+declare const badgeVariants: (props?: ({
+    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Badge({ className, variant, asChild, ...props }: React__default.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function Separator({ className, orientation, decorative, ...props }: React__default.ComponentProps<typeof Separator$1.Root>): react_jsx_runtime.JSX.Element;
+
+declare function ScrollArea({ className, children, ...props }: React__default.ComponentProps<typeof ScrollArea$1.Root>): react_jsx_runtime.JSX.Element;
+declare function ScrollBar({ className, orientation, ...props }: React__default.ComponentProps<typeof ScrollArea$1.ScrollAreaScrollbar>): react_jsx_runtime.JSX.Element;
+
+declare function Dialog({ ...props }: React__default.ComponentProps<typeof Dialog$1.Root>): react_jsx_runtime.JSX.Element;
+declare function DialogTrigger({ ...props }: React__default.ComponentProps<typeof Dialog$1.Trigger>): react_jsx_runtime.JSX.Element;
+declare function DialogClose({ ...props }: React__default.ComponentProps<typeof Dialog$1.Close>): react_jsx_runtime.JSX.Element;
+declare function DialogContent({ className, children, showCloseButton, ...props }: React__default.ComponentProps<typeof Dialog$1.Content> & {
+    showCloseButton?: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DialogHeader({ className, ...props }: React__default.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
+declare function DialogFooter({ className, showCloseButton, children, ...props }: React__default.ComponentProps<"div"> & {
+    showCloseButton?: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DialogTitle({ className, ...props }: React__default.ComponentProps<typeof Dialog$1.Title>): react_jsx_runtime.JSX.Element;
+declare function DialogDescription({ className, ...props }: React__default.ComponentProps<typeof Dialog$1.Description>): react_jsx_runtime.JSX.Element;
+
+declare function DropdownMenu({ ...props }: React__default.ComponentProps<typeof DropdownMenu$1.Root>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuTrigger({ ...props }: React__default.ComponentProps<typeof DropdownMenu$1.Trigger>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuContent({ className, sideOffset, ...props }: React__default.ComponentProps<typeof DropdownMenu$1.Content>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuItem({ className, inset, variant, ...props }: React__default.ComponentProps<typeof DropdownMenu$1.Item> & {
+    inset?: boolean;
+    variant?: "default" | "destructive";
+}): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuSeparator({ className, ...props }: React__default.ComponentProps<typeof DropdownMenu$1.Separator>): react_jsx_runtime.JSX.Element;
+
+declare function Label({ className, ...props }: React__default.ComponentProps<typeof Label$1.Root>): react_jsx_runtime.JSX.Element;
+
+declare function Switch({ className, ...props }: React__default.ComponentProps<typeof Switch$1.Root>): react_jsx_runtime.JSX.Element;
+
+declare function Textarea({ className, ...props }: React__default.ComponentProps<"textarea">): react_jsx_runtime.JSX.Element;
+
+declare function Popover({ ...props }: React__default.ComponentProps<typeof Popover$1.Root>): react_jsx_runtime.JSX.Element;
+declare function PopoverTrigger({ ...props }: React__default.ComponentProps<typeof Popover$1.Trigger>): react_jsx_runtime.JSX.Element;
+declare function PopoverContent({ className, align, sideOffset, ...props }: React__default.ComponentProps<typeof Popover$1.Content>): react_jsx_runtime.JSX.Element;
+
+declare function Tabs({ ...props }: React__default.ComponentProps<typeof Tabs$1.Root>): react_jsx_runtime.JSX.Element;
+declare function TabsList({ className, ...props }: React__default.ComponentProps<typeof Tabs$1.List>): react_jsx_runtime.JSX.Element;
+declare function TabsTrigger({ className, ...props }: React__default.ComponentProps<typeof Tabs$1.Trigger>): react_jsx_runtime.JSX.Element;
+declare function TabsContent({ className, ...props }: React__default.ComponentProps<typeof Tabs$1.Content>): react_jsx_runtime.JSX.Element;
+
+declare function ValueInput({ value, onChange, placeholder }: ValueInputProps): react_jsx_runtime.JSX.Element;
+
+declare function DateTimeInput({ value, onChange }: DateTimeInputProps): react_jsx_runtime.JSX.Element;
+
+declare function ValidationMessage({ errors }: ValidationMessageProps): react_jsx_runtime.JSX.Element | null;
+
+declare function ThemeToggle({ theme, onToggle }: ThemeToggleProps): react_jsx_runtime.JSX.Element;
+
+type ErrorBoundaryProps = {
+    children: ReactNode;
+    /** Optional fallback to render instead of the default error UI. */
+    fallback?: ReactNode;
+    /** Called when an error is caught. Defaults to console.error. */
+    onError?: (error: Error, info: ErrorInfo) => void;
+};
+type ErrorBoundaryState = {
+    error: Error | null;
+};
+/**
+ * A class component error boundary that catches render errors in its subtree
+ * and displays a fallback UI with the error message and a "Try again" button.
+ */
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    handleRetry: () => void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+type ConfirmDialogProps = {
+    title: string;
+    description: React__default.ReactNode;
+    actionLabel: string;
+    onConfirm: () => void;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: React__default.ReactNode;
+};
+declare function ConfirmDialog({ title, description, actionLabel, onConfirm, open, onOpenChange, children, }: ConfirmDialogProps): react_jsx_runtime.JSX.Element;
+
+declare function ConditionBuilder({ conditions: rawConditions, onChange, validationErrors, }: ConditionBuilderProps): react_jsx_runtime.JSX.Element;
+
+declare const VariationCard: React$1.NamedExoticComponent<VariationCardProps>;
+
+declare function VariationList({ variations: rawVariations, validationErrors, onChange, }: VariationListProps): react_jsx_runtime.JSX.Element;
+
+declare function DefinitionEditor({ definitionKey, definition, validationErrors, isDirty, isPending, onUpdate, onRename, onSave, onDiscard, }: DefinitionEditorProps): react_jsx_runtime.JSX.Element;
+
+declare function DefinitionList({ definitions, selectedKey, validationErrors, dirtyKeys, onSelect, onAdd, onRemove, }: DefinitionListProps): react_jsx_runtime.JSX.Element;
+
+interface ConditionExtensions {
+    extraConditionTypes: ConditionTypeMeta[];
+    editorOverrides: Map<string, ComponentType<ConditionValueEditorProps>>;
+}
+
+declare function createPresetConditionMeta(presets: Presets): ConditionTypeMeta[];
+declare function createPresetUI(presets: Presets): ConditionExtensions;
+
+interface ValidationIssue {
+    path: (string | number)[];
+    message: string;
+}
+/** Tracks whether an async store action is in flight or has failed. */
+interface ActionState {
+    pending: boolean;
+    error: Error | null;
+}
+/** External-store source shape for subscription-backed selectors. */
+interface ConfiguratorStoreSource {
+    getSnapshot: () => ConfiguratorStore;
+    subscribe: (listener: () => void) => () => void;
+}
+/**
+ * Store contract any shell must implement.
+ * All commands are async to support API-backed implementations.
+ */
+interface ConfiguratorStore {
+    definitions: Definitions;
+    selectedKey: string | null;
+    dirtyKeys: string[];
+    revision: number;
+    validationErrors: Record<string, ValidationIssue[]>;
+    isKeyDirty(key: string): boolean;
+    selectDefinition(key: string | null): Promise<void>;
+    addDefinition(key: string): Promise<void>;
+    removeDefinition(key: string): Promise<void>;
+    renameDefinition(oldKey: string, newKey: string): Promise<void>;
+    updateDefinition(key: string, def: Definition): Promise<void>;
+    saveDefinition(key: string): Promise<void>;
+    discardDefinition(key: string): Promise<void>;
+}
+
+declare function Configurator({ store, className, emptyState, conditionExtensions, fallbackEvaluator, }: {
+    store: ConfiguratorStore | ConfiguratorStoreSource;
+    className?: string;
+    emptyState?: React.ReactNode;
+    conditionExtensions?: ConditionExtensions;
+    fallbackEvaluator?: ConditionEvaluator;
+}): react_jsx_runtime.JSX.Element;
+
+interface ActionStateContextValue {
+    actionState: ActionState;
+    runAction: (action: () => Promise<void>) => Promise<void>;
+    clearError: () => void;
+}
+/** Carries only the store source — changes rarely (only when the store identity changes). */
+declare const StoreSourceContext: React$1.Context<ConfiguratorStoreSource | null>;
+/** Carries action state (pending / error) — changes on every async action lifecycle event. */
+declare const ActionStateContext: React$1.Context<ActionStateContextValue | null>;
+declare function useConfiguratorStore(): ConfiguratorStore;
+declare function useActionState(): ActionStateContextValue;
+/**
+ * Returns a stable getter for the current store snapshot.
+ * Use this to call store methods in event handlers without
+ * subscribing the component to store changes.
+ */
+declare function useStoreRef(): () => ConfiguratorStore;
+
+/**
+ * Select a slice of the ConfiguratorStore with subscription-level
+ * short-circuiting.  The component only rerenders when the selected
+ * value changes (via `Object.is` equality).
+ *
+ * Reads only from StoreSourceContext so action-state changes
+ * (pending / error) do NOT trigger rerenders in selector consumers.
+ */
+declare function useConfiguratorSelector<T>(selector: (store: ConfiguratorStore) => T): T;
+
+type PreviewResult = {
+    status: "success";
+    value: unknown;
+    meta: Resolution["meta"];
+} | {
+    status: "inactive";
+    message: string;
+} | {
+    status: "no-match";
+    message: string;
+} | {
+    status: "error";
+    message: string;
+};
+
+export { AUTO_ID_PREFIX, type ActionState, ActionStateContext, type ActionStateContextValue, BUILTIN_CONDITION_TYPES, Badge, Button, CONDITION_TYPE_MAP, type ConditionBlockProps, ConditionBuilder, type ConditionBuilderProps, type ConditionExtensions, type ConditionGroupProps, type ConditionTypeMeta, type ConditionValueEditorProps, Configurator, type ConfiguratorStore, type ConfiguratorStoreSource, ConfirmDialog, DateTimeInput, type DateTimeInputProps, DefinitionEditor, type DefinitionEditorProps, DefinitionList, type DefinitionListItemProps, type DefinitionListProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, ErrorBoundary, Input, Label, Popover, PopoverContent, PopoverTrigger, type PreviewResult, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, StoreSourceContext, Switch, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, ThemeToggle, type ThemeToggleProps, type ValidationIssue, type ValidationIssueDisplay, ValidationMessage, type ValidationMessageProps, ValueInput, type ValueInputProps, VariationCard, type VariationCardProps, VariationList, type VariationListProps, badgeVariants, buttonVariants, cn, createPresetConditionMeta, createPresetUI, getConditionMeta, isAutoId, stripAutoIds, useActionState, useConfiguratorSelector, useConfiguratorStore, useStoreRef };