@fuf-stack/megapixels 0.0.1 → 0.1.0

package/dist/Filter/index.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunkXMMMIB2Ccjs = require('../chunk-XMMMIB2C.cjs');
+
+
+
+
+exports.createFilter = _chunkXMMMIB2Ccjs.createFilter_default; exports.default = _chunkXMMMIB2Ccjs.Filter_default; exports.filters = _chunkXMMMIB2Ccjs.filters;
+//# sourceMappingURL=index.cjs.map

package/dist/Filter/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/megapixels/dist/Filter/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACF,+JAAC","file":"/home/runner/work/pixels/pixels/packages/megapixels/dist/Filter/index.cjs"}

package/dist/Filter/index.d.cts

@@ -0,0 +1,219 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * FilterDefinition
+ *
+ * Declarative description of a filter. A FilterDefinition is not used
+ * directly by the UI. Instead, it is passed to `createFilter` to produce a
+ * concrete, runtime `FilterInstance` for a specific usage (with name/icon and
+ * optional config overrides).
+ *
+ * @typeParam Config - The configuration object shape for this filter
+ * @typeParam Value  - The runtime value type produced/consumed by this filter
+ */
+interface FilterDefinition<Config, Value> {
+    components: {
+        /**
+         * Display component rendered inside the filter chip. Receives the current
+         * filter `value` and the merged `config`.
+         */
+        Display: (props: {
+            value: Value;
+            config: Config;
+        }) => ReactNode;
+        /**
+         * Form component rendered inside the modal. Receives the fully-qualified
+         * field name and the merged, validated `config`.
+         */
+        Form: (props: {
+            fieldName: string;
+            config: Config;
+        }) => ReactNode;
+    };
+    defaults: {
+        /** Baseline configuration for the filter; can be overridden per usage */
+        config: Config;
+        /** Initial form value seeded when a filter is added */
+        value: Value;
+    };
+    /**
+     * Validation factory returning an ex-validator schema for the value shape.
+     * Receives the (merged) `config` so the schema can depend on configuration.
+     */
+    validation: (config?: Config) => unknown;
+}
+/**
+ * FilterFactory
+ *
+ * A filter exports a factory that, given name/icon and optional config
+ * overrides, returns a concrete FilterInstance with merged config and a
+ * computed defaultValue.
+ *
+ * @typeParam Config - Configuration object shape for the filter
+ * @typeParam Value  - Runtime value type for the filter
+ */
+type FilterFactory<Config, Value> = (args: {
+    /** Per-usage configuration overrides merged with `defaults.config` */
+    config?: Partial<Config>;
+    /** Optional icon element shown in menus/labels */
+    icon?: ReactNode;
+    /** Logical field name under `filter.{name}` */
+    name: string;
+}) => FilterInstance<Config, Value>;
+/**
+ * FilterInstance
+ *
+ * Runtime instance created by merging a filter's defaults with usage
+ * overrides and attaching name/icon for UI.
+ *
+ * This is the only shape used by the rendering layer and context.
+ *
+ * @typeParam Config - Effective configuration object shape
+ * @typeParam Value  - Effective value type for the filter
+ */
+interface FilterInstance<Config, Value> {
+    /** UI components (Form/Display) provided by the filter */
+    components: FilterDefinition<Config, Value>['components'];
+    /** Merged configuration (`defaults.config` overlaid with per-usage overrides) */
+    config: Config;
+    /** Initial form value to seed when adding this filter */
+    defaultValue: Value;
+    /** Optional icon element used in menus/labels */
+    icon?: ReactNode;
+    /** Logical field name under `filter.{name}` */
+    name: string;
+    /** ex-validator schema factory for the value; typically closure over config */
+    validation: (config?: Config) => unknown;
+}
+/**
+ * FiltersConfiguration
+ *
+ * Top-level collection of instantiated filters used by the Filter component
+ * and FiltersContext. Each entry is a concrete FilterInstance (already created
+ * via a filter factory), carrying its merged config, default value, UI
+ * components, and validate function.
+ */
+type FiltersConfiguration = FilterInstance<any, any>[];
+/**
+ * FilterDisplayProps
+ *
+ * Props provided to a filter's Display component. Derived from an active
+ * FilterInstance at runtime.
+ *
+ * @typeParam Config - Effective configuration type for the instance
+ * @typeParam Value  - Effective value type for the instance
+ */
+interface FilterDisplayProps<Config, Value> {
+    /** Merged configuration for the filter instance */
+    config: Config;
+    /** Current (possibly partial) value for the filter instance */
+    value: Value;
+}
+/**
+ * FilterFormProps
+ *
+ * Props provided to a filter's Form component. The `fieldName` is the
+ * fully-qualified path in the host form, and the `config` is the instance's
+ * merged configuration.
+ *
+ * @typeParam Config - Effective configuration type for the instance
+ */
+interface FilterFormProps<Config> {
+    /** Merged configuration for the filter instance */
+    config: Config;
+    /** Fully-qualified form field path (e.g., `filter.status`) */
+    fieldName: string;
+}
+
+type SearchConfiguration = boolean | {
+    /** Placeholder shown in the search input */
+    placeholder?: string;
+};
+
+interface FilterValues {
+    search?: string;
+    filter?: string | Record<string, unknown>;
+}
+type FilterChildRenderFn = (values: FilterValues) => ReactNode;
+/**
+ * Filter
+ *
+ * Controlled, form-driven filter UI.
+ *
+ * Responsibilities
+ * - Derives initial form values from the controlled `values` prop
+ * - Builds a composite validation schema from the filter registry (and optional search)
+ * - Exposes ergonomic UI: active filters list, add/remove actions, and per-filter modal
+ * - Commits changes by invoking the controlled `onChange` callback on submit
+ *
+ * Structure
+ * - Owns an ex-forms `Form` that wraps the entire filter experience
+ * - Optionally renders a search input bound to the `search` field
+ * - Renders ActiveFilters, AddFilterMenu, and FilterModal inside a shared context
+ * - Optionally renders children as a render-prop with the resolved `values`
+ */
+interface FilterProps {
+    /** Optional render-prop that receives the resolved, controlled values */
+    children?: FilterChildRenderFn;
+    /** CSS class name */
+    className?: string;
+    /** Configuration of the filter */
+    config: {
+        /**
+         * Declarative filter configuration. Each entry ties a logical name to a
+         * registry filter type and (optionally) per-usage config overrides.
+         */
+        filters: FiltersConfiguration;
+        /** Optional configuration for search field */
+        search?: SearchConfiguration;
+    };
+    /** ex-forms form instance name. Defaults to "filterComponentForm". */
+    formName?: string;
+    /** Controlled setter invoked on submit with the next canonical values */
+    onChange: (nextValues: FilterValues) => void;
+    /** Controlled committed state: the canonical `search` and `filter` values */
+    values: FilterValues;
+}
+/**
+ * Renders the filter UI bound to a single ex-forms `Form`.
+ * The form is the source of truth during user interaction; the committed
+ * state is controlled by the parent via `values`/`onChange`.
+ */
+declare const Filter: ({ children, className, config, formName, onChange, values, }: FilterProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * createFilter
+ *
+ * Builds a filter factory from a static FilterDefinition. The returned factory
+ * accepts a usage descriptor (name/icon and optional partial config) and
+ * produces a concrete FilterInstance with:
+ * - merged config (shallow: definition.defaults.config overlaid by overrides)
+ * - Form/Display components
+ * - validate function (forwarded from the definition)
+ * - defaultValue (forwarded from the definition)
+ * - name and icon for UI integration
+ *
+ * @typeParam Config - Configuration object shape for the filter
+ * @typeParam Value  - Runtime value type for the filter
+ * @param definition - Static description of the filter (components, defaults, validate)
+ * @returns FilterFactory that creates FilterInstance<Config, Value>
+ */
+declare const createFilter: <Config, Value>(definition: FilterDefinition<Config, Value>) => FilterFactory<Config, Value>;
+
+declare const filters: {
+    boolean: FilterFactory<{
+        text: string;
+        textPrefix?: string | undefined;
+        textNoWord?: string | undefined;
+    }, boolean | undefined>;
+    checkboxgroup: FilterFactory<{
+        text: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+    }, string[]>;
+};
+
+export { type FilterDefinition, type FilterDisplayProps, type FilterFactory, type FilterFormProps, type FilterInstance, type FiltersConfiguration, createFilter, Filter as default, filters };

package/dist/Filter/index.d.ts

@@ -0,0 +1,219 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * FilterDefinition
+ *
+ * Declarative description of a filter. A FilterDefinition is not used
+ * directly by the UI. Instead, it is passed to `createFilter` to produce a
+ * concrete, runtime `FilterInstance` for a specific usage (with name/icon and
+ * optional config overrides).
+ *
+ * @typeParam Config - The configuration object shape for this filter
+ * @typeParam Value  - The runtime value type produced/consumed by this filter
+ */
+interface FilterDefinition<Config, Value> {
+    components: {
+        /**
+         * Display component rendered inside the filter chip. Receives the current
+         * filter `value` and the merged `config`.
+         */
+        Display: (props: {
+            value: Value;
+            config: Config;
+        }) => ReactNode;
+        /**
+         * Form component rendered inside the modal. Receives the fully-qualified
+         * field name and the merged, validated `config`.
+         */
+        Form: (props: {
+            fieldName: string;
+            config: Config;
+        }) => ReactNode;
+    };
+    defaults: {
+        /** Baseline configuration for the filter; can be overridden per usage */
+        config: Config;
+        /** Initial form value seeded when a filter is added */
+        value: Value;
+    };
+    /**
+     * Validation factory returning an ex-validator schema for the value shape.
+     * Receives the (merged) `config` so the schema can depend on configuration.
+     */
+    validation: (config?: Config) => unknown;
+}
+/**
+ * FilterFactory
+ *
+ * A filter exports a factory that, given name/icon and optional config
+ * overrides, returns a concrete FilterInstance with merged config and a
+ * computed defaultValue.
+ *
+ * @typeParam Config - Configuration object shape for the filter
+ * @typeParam Value  - Runtime value type for the filter
+ */
+type FilterFactory<Config, Value> = (args: {
+    /** Per-usage configuration overrides merged with `defaults.config` */
+    config?: Partial<Config>;
+    /** Optional icon element shown in menus/labels */
+    icon?: ReactNode;
+    /** Logical field name under `filter.{name}` */
+    name: string;
+}) => FilterInstance<Config, Value>;
+/**
+ * FilterInstance
+ *
+ * Runtime instance created by merging a filter's defaults with usage
+ * overrides and attaching name/icon for UI.
+ *
+ * This is the only shape used by the rendering layer and context.
+ *
+ * @typeParam Config - Effective configuration object shape
+ * @typeParam Value  - Effective value type for the filter
+ */
+interface FilterInstance<Config, Value> {
+    /** UI components (Form/Display) provided by the filter */
+    components: FilterDefinition<Config, Value>['components'];
+    /** Merged configuration (`defaults.config` overlaid with per-usage overrides) */
+    config: Config;
+    /** Initial form value to seed when adding this filter */
+    defaultValue: Value;
+    /** Optional icon element used in menus/labels */
+    icon?: ReactNode;
+    /** Logical field name under `filter.{name}` */
+    name: string;
+    /** ex-validator schema factory for the value; typically closure over config */
+    validation: (config?: Config) => unknown;
+}
+/**
+ * FiltersConfiguration
+ *
+ * Top-level collection of instantiated filters used by the Filter component
+ * and FiltersContext. Each entry is a concrete FilterInstance (already created
+ * via a filter factory), carrying its merged config, default value, UI
+ * components, and validate function.
+ */
+type FiltersConfiguration = FilterInstance<any, any>[];
+/**
+ * FilterDisplayProps
+ *
+ * Props provided to a filter's Display component. Derived from an active
+ * FilterInstance at runtime.
+ *
+ * @typeParam Config - Effective configuration type for the instance
+ * @typeParam Value  - Effective value type for the instance
+ */
+interface FilterDisplayProps<Config, Value> {
+    /** Merged configuration for the filter instance */
+    config: Config;
+    /** Current (possibly partial) value for the filter instance */
+    value: Value;
+}
+/**
+ * FilterFormProps
+ *
+ * Props provided to a filter's Form component. The `fieldName` is the
+ * fully-qualified path in the host form, and the `config` is the instance's
+ * merged configuration.
+ *
+ * @typeParam Config - Effective configuration type for the instance
+ */
+interface FilterFormProps<Config> {
+    /** Merged configuration for the filter instance */
+    config: Config;
+    /** Fully-qualified form field path (e.g., `filter.status`) */
+    fieldName: string;
+}
+
+type SearchConfiguration = boolean | {
+    /** Placeholder shown in the search input */
+    placeholder?: string;
+};
+
+interface FilterValues {
+    search?: string;
+    filter?: string | Record<string, unknown>;
+}
+type FilterChildRenderFn = (values: FilterValues) => ReactNode;
+/**
+ * Filter
+ *
+ * Controlled, form-driven filter UI.
+ *
+ * Responsibilities
+ * - Derives initial form values from the controlled `values` prop
+ * - Builds a composite validation schema from the filter registry (and optional search)
+ * - Exposes ergonomic UI: active filters list, add/remove actions, and per-filter modal
+ * - Commits changes by invoking the controlled `onChange` callback on submit
+ *
+ * Structure
+ * - Owns an ex-forms `Form` that wraps the entire filter experience
+ * - Optionally renders a search input bound to the `search` field
+ * - Renders ActiveFilters, AddFilterMenu, and FilterModal inside a shared context
+ * - Optionally renders children as a render-prop with the resolved `values`
+ */
+interface FilterProps {
+    /** Optional render-prop that receives the resolved, controlled values */
+    children?: FilterChildRenderFn;
+    /** CSS class name */
+    className?: string;
+    /** Configuration of the filter */
+    config: {
+        /**
+         * Declarative filter configuration. Each entry ties a logical name to a
+         * registry filter type and (optionally) per-usage config overrides.
+         */
+        filters: FiltersConfiguration;
+        /** Optional configuration for search field */
+        search?: SearchConfiguration;
+    };
+    /** ex-forms form instance name. Defaults to "filterComponentForm". */
+    formName?: string;
+    /** Controlled setter invoked on submit with the next canonical values */
+    onChange: (nextValues: FilterValues) => void;
+    /** Controlled committed state: the canonical `search` and `filter` values */
+    values: FilterValues;
+}
+/**
+ * Renders the filter UI bound to a single ex-forms `Form`.
+ * The form is the source of truth during user interaction; the committed
+ * state is controlled by the parent via `values`/`onChange`.
+ */
+declare const Filter: ({ children, className, config, formName, onChange, values, }: FilterProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * createFilter
+ *
+ * Builds a filter factory from a static FilterDefinition. The returned factory
+ * accepts a usage descriptor (name/icon and optional partial config) and
+ * produces a concrete FilterInstance with:
+ * - merged config (shallow: definition.defaults.config overlaid by overrides)
+ * - Form/Display components
+ * - validate function (forwarded from the definition)
+ * - defaultValue (forwarded from the definition)
+ * - name and icon for UI integration
+ *
+ * @typeParam Config - Configuration object shape for the filter
+ * @typeParam Value  - Runtime value type for the filter
+ * @param definition - Static description of the filter (components, defaults, validate)
+ * @returns FilterFactory that creates FilterInstance<Config, Value>
+ */
+declare const createFilter: <Config, Value>(definition: FilterDefinition<Config, Value>) => FilterFactory<Config, Value>;
+
+declare const filters: {
+    boolean: FilterFactory<{
+        text: string;
+        textPrefix?: string | undefined;
+        textNoWord?: string | undefined;
+    }, boolean | undefined>;
+    checkboxgroup: FilterFactory<{
+        text: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+    }, string[]>;
+};
+
+export { type FilterDefinition, type FilterDisplayProps, type FilterFactory, type FilterFormProps, type FilterInstance, type FiltersConfiguration, createFilter, Filter as default, filters };

package/dist/Filter/index.js

@@ -0,0 +1,11 @@
+import {
+  Filter_default,
+  createFilter_default,
+  filters
+} from "../chunk-X574WZ6N.js";
+export {
+  createFilter_default as createFilter,
+  Filter_default as default,
+  filters
+};
+//# sourceMappingURL=index.js.map

package/dist/Filter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}