@ponti-studios/ui 0.6.0 → 0.7.0

package/src/components/layout/index.ts

@@ -1,5 +1,7 @@
 export { ScrollArea } from "./scroll-area";
 export type { ScrollAreaProps } from "./scroll-area";
+export { SearchFilterBar } from "../filters/search-filter-bar";
+export type { SearchFilterBarProps } from "../filters/search-filter-bar";
 export { SectionIntro } from "./section-intro";
 export type { SectionIntroProps } from "./section-intro";
 export { SurfacePanel } from "./surface-panel";

package/src/hooks/index.ts

@@ -1,5 +1,7 @@
 export { useApiClient } from "./use-api-client";
 export { useDebouncedValue } from "./use-debounced-value";
+export { useDerivedFilterState } from "./use-derived-filter-state";
+export type { FilterConfig } from "./use-derived-filter-state";
 export { useFilterState } from "./use-filter-state";
 export { useMediaQuery } from "./use-media-query";
 export { useIsMobile } from "./use-mobile";

package/src/hooks/use-derived-filter-state.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
+import { useRef } from 'react';
+
+import { useDerivedFilterState, type FilterConfig } from './use-derived-filter-state';
+
+function createMemorySync(initial: Record<string, string>) {
+  const store = { ...initial };
+  return {
+    read: () => ({ ...store }),
+    write: (values: Record<string, string>) => Object.assign(store, values),
+  };
+}
+
+const fields = {
+  status: { default: "", label: (v: string) => `Status: ${v}` } satisfies FilterConfig,
+  search: { default: "" } satisfies FilterConfig,
+};
+
+function Harness() {
+  const sync = useRef(createMemorySync({ status: "", search: "" }));
+  const { values, setValue, activeFilters, clearAll, hasActive } =
+    useDerivedFilterState({ fields, sync: sync.current });
+
+  return (
+    <div data-testid="harness">
+      <span data-testid="values">{JSON.stringify(values)}</span>
+      <span data-testid="active-filters">
+        {activeFilters.map((f) => f.label).join(',')}
+      </span>
+      <span data-testid="has-active">{String(hasActive)}</span>
+      <button
+        data-testid="set-status"
+        onClick={() => setValue('status', 'active')}
+      >
+        Set status
+      </button>
+      <button
+        data-testid="set-search"
+        onClick={() => setValue('search', 'hello')}
+      >
+        Set search
+      </button>
+      <button
+        data-testid="clear-status"
+        onClick={() => setValue('status', '')}
+      >
+        Clear status
+      </button>
+      <button data-testid="clear-all" onClick={() => clearAll()}>
+        Clear all
+      </button>
+    </div>
+  );
+}
+
+const meta: Meta<typeof Harness> = {
+  title: 'Internal/useDerivedFilterState',
+  component: Harness,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const InitialState: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId('values')).toHaveTextContent(
+      '{"status":"","search":""}',
+    );
+    await expect(canvas.getByTestId('has-active')).toHaveTextContent('false');
+    await expect(canvas.getByTestId('active-filters')).toHaveTextContent('');
+  },
+};
+
+export const SetValueCreatesActiveFilter: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('set-status'));
+    await expect(canvas.getByTestId('values')).toHaveTextContent(
+      '{"status":"active","search":""}',
+    );
+    await expect(canvas.getByTestId('active-filters')).toHaveTextContent(
+      'Status: active',
+    );
+    await expect(canvas.getByTestId('has-active')).toHaveTextContent('true');
+  },
+};
+
+export const ClearValueRemovesActiveFilter: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('set-status'));
+    await userEvent.click(canvas.getByTestId('clear-status'));
+    await expect(canvas.getByTestId('values')).toHaveTextContent(
+      '{"status":"","search":""}',
+    );
+    await expect(canvas.getByTestId('has-active')).toHaveTextContent('false');
+  },
+};
+
+export const ClearAllResetsEverything: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('set-status'));
+    await userEvent.click(canvas.getByTestId('set-search'));
+    await userEvent.click(canvas.getByTestId('clear-all'));
+    await expect(canvas.getByTestId('values')).toHaveTextContent(
+      '{"status":"","search":""}',
+    );
+    await expect(canvas.getByTestId('has-active')).toHaveTextContent('false');
+    await expect(canvas.getByTestId('active-filters')).toHaveTextContent('');
+  },
+};
+
+export const ActiveFilterOnRemoveClearsValue: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('set-status'));
+    await expect(canvas.getByTestId('active-filters')).toHaveTextContent(
+      'Status: active',
+    );
+  },
+};
+
+export const MultipleActiveFilters: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('set-status'));
+    await userEvent.click(canvas.getByTestId('set-search'));
+    await expect(canvas.getByTestId('active-filters')).toHaveTextContent(
+      'Status: active,search: hello',
+    );
+  },
+};

package/src/hooks/use-derived-filter-state.ts

@@ -0,0 +1,72 @@
+import { useCallback, useMemo, useState } from "react";
+
+import type { ActiveFilter } from "../components/filters/active-filters-bar";
+
+export interface FilterConfig {
+  default: string;
+  label?: (value: string) => string;
+}
+
+interface UseDerivedFilterStateOptions<T extends Record<string, FilterConfig>> {
+  fields: T;
+  sync: {
+    read: () => Record<string, string>;
+    write: (values: Record<string, string>) => void;
+  };
+}
+
+export function useDerivedFilterState<T extends Record<string, FilterConfig>>({
+  fields,
+  sync,
+}: UseDerivedFilterStateOptions<T>) {
+  const [values, setValues] = useState<Record<string, string>>(() => {
+    const read = sync.read();
+    const initial: Record<string, string> = {};
+    for (const key of Object.keys(fields)) {
+      initial[key] = read[key] ?? fields[key].default;
+    }
+    return initial;
+  });
+
+  const setValue = useCallback(
+    (key: string, value: string) => {
+      setValues((prev) => {
+        const next = { ...prev, [key]: value };
+        sync.write(next);
+        return next;
+      });
+    },
+    [sync],
+  );
+
+  const clearAll = useCallback(() => {
+    const reset: Record<string, string> = {};
+    for (const key of Object.keys(fields)) {
+      reset[key] = fields[key].default;
+    }
+    setValues(reset);
+    sync.write(reset);
+  }, [fields, sync]);
+
+  const activeFilters: ActiveFilter[] = useMemo(() => {
+    return Object.entries(values)
+      .filter(([, v]) => v !== "")
+      .map(([key, v]) => ({
+        id: key,
+        label: fields[key]?.label
+          ? fields[key].label!(v)
+          : `${key}: ${v}`,
+        onRemove: () => setValue(key, ""),
+      }));
+  }, [values, fields, setValue]);
+
+  const hasActive = activeFilters.length > 0;
+
+  return {
+    values,
+    setValue,
+    activeFilters,
+    clearAll,
+    hasActive,
+  };
+}

package/src/hooks/use-filter-state.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
+import { useFilterState } from './use-filter-state';
+
+type Filters = Record<string, string>;
+
+function Harness({
+  initialFilters,
+  debounceMs,
+}: {
+  initialFilters: Filters;
+  debounceMs?: number;
+}) {
+  const { filters, updateFilter, setFilters, clearFilters } = useFilterState<Filters>({
+    initialFilters,
+    debounceMs,
+  });
+
+  return (
+    <div data-testid="harness">
+      <span data-testid="filters">{JSON.stringify(filters)}</span>
+      <button
+        data-testid="update-status"
+        onClick={() => updateFilter('status', 'active')}
+      >
+        Set status to active
+      </button>
+      <button
+        data-testid="update-search"
+        onClick={() => updateFilter('search', 'hello')}
+      >
+        Set search to hello
+      </button>
+      <button
+        data-testid="set-filters"
+        onClick={() => setFilters({ status: 'rejected', search: 'test' })}
+      >
+        Set all filters
+      </button>
+      <button data-testid="clear" onClick={() => clearFilters()}>
+        Clear
+      </button>
+    </div>
+  );
+}
+
+const meta: Meta<typeof Harness> = {
+  title: 'Internal/useFilterState',
+  component: Harness,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const InitialState: Story = {
+  args: {
+    initialFilters: { status: '', search: '' },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const output = canvas.getByTestId('filters');
+    await expect(output).toHaveTextContent('{"status":"","search":""}');
+  },
+};
+
+export const UpdateSingleFilter: Story = {
+  args: {
+    initialFilters: { status: '', search: '' },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('update-status'));
+    const output = canvas.getByTestId('filters');
+    await expect(output).toHaveTextContent('{"status":"active","search":""}');
+  },
+};
+
+export const SetAllFilters: Story = {
+  args: {
+    initialFilters: { status: '', search: '' },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('set-filters'));
+    const output = canvas.getByTestId('filters');
+    await expect(output).toHaveTextContent('{"status":"rejected","search":"test"}');
+  },
+};
+
+export const ClearResetsToInitial: Story = {
+  args: {
+    initialFilters: { status: 'pending', search: 'default' },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByTestId('update-status'));
+    await userEvent.click(canvas.getByTestId('clear'));
+    const output = canvas.getByTestId('filters');
+    await expect(output).toHaveTextContent('{"status":"pending","search":"default"}');
+  },
+};

package/src/hooks/use-filter-state.ts

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 interface UseFilterStateOptions<T> {
   initialFilters: T;
   onFiltersChange?: (filters: T) => void;
-  debounceMs?: number; // For search-like filters
+  debounceMs?: number;
 }
 
 export function useFilterState<T extends Record<string, unknown>>(
@@ -12,24 +12,30 @@ export function useFilterState<T extends Record<string, unknown>>(
   const { initialFilters, onFiltersChange, debounceMs } = options;
   const [filters, setFiltersState] = useState<T>(initialFilters);
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onFiltersChangeRef = useRef(onFiltersChange);
+  onFiltersChangeRef.current = onFiltersChange;
 
   const setFilters = useCallback(
     (newFilters: T | ((prev: T) => T)) => {
-      const updatedFilters = typeof newFilters === "function" ? newFilters(filters) : newFilters;
-      setFiltersState(updatedFilters);
+      setFiltersState((prev) => {
+        const updatedFilters =
+          typeof newFilters === "function" ? newFilters(prev) : newFilters;
 
-      if (debounceMs && debounceMs > 0) {
-        if (debounceTimerRef.current) {
-          clearTimeout(debounceTimerRef.current);
+        if (debounceMs && debounceMs > 0) {
+          if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+          }
+          debounceTimerRef.current = setTimeout(() => {
+            onFiltersChangeRef.current?.(updatedFilters);
+          }, debounceMs);
+        } else {
+          onFiltersChangeRef.current?.(updatedFilters);
         }
-        debounceTimerRef.current = setTimeout(() => {
-          onFiltersChange?.(updatedFilters);
-        }, debounceMs);
-      } else {
-        onFiltersChange?.(updatedFilters);
-      }
+
+        return updatedFilters;
+      });
     },
-    [filters, onFiltersChange, debounceMs],
+    [debounceMs],
   );
 
   const updateFilter = useCallback(
@@ -41,15 +47,9 @@ export function useFilterState<T extends Record<string, unknown>>(
 
   const clearFilters = useCallback(() => {
     setFiltersState(initialFilters);
-    onFiltersChange?.(initialFilters);
-  }, [initialFilters, onFiltersChange]);
-
-  const resetFilters = useCallback(() => {
-    setFiltersState(initialFilters);
-    onFiltersChange?.(initialFilters);
-  }, [initialFilters, onFiltersChange]);
+    onFiltersChangeRef.current?.(initialFilters);
+  }, [initialFilters]);
 
-  // Cleanup debounce timer on unmount
   useEffect(() => {
     return () => {
       if (debounceTimerRef.current) {
@@ -63,6 +63,5 @@ export function useFilterState<T extends Record<string, unknown>>(
     setFilters,
     updateFilter,
     clearFilters,
-    resetFilters,
   };
 }

package/src/index.ts

@@ -2,6 +2,8 @@ export { CHART_COLORS, CHART_CSS_VARS } from "./constants/chart-colors";
 export type { SortDirection, SortField, SortOption } from "./hooks/sort.types";
 export { useApiClient } from "./hooks/use-api-client";
 export { useDebouncedValue } from "./hooks/use-debounced-value";
+export { useDerivedFilterState } from "./hooks/use-derived-filter-state";
+export type { FilterConfig } from "./hooks/use-derived-filter-state";
 export { useFilterState } from "./hooks/use-filter-state";
 export { useMediaQuery } from "./hooks/use-media-query";
 export { useIsMobile } from "./hooks/use-mobile";

package/src/styles/index.css

@@ -90,6 +90,37 @@
 @utility min-h-screen-dynamic {
   min-height: 100dvh;
 }
+/* ── scroll-fade ──
+ * Progressive opacity mask on scroll-container edges.
+ * Uses CSS custom properties so consumers can override the fade size
+ * or disable the mask without a class order dependency:
+ *
+ *   <div class="scroll-fade-x overflow-x-auto [--scroll-fade-size:24px]">
+ *   <div class="scroll-fade-y overflow-y-auto scroll-fade-none md:scroll-fade">
+ *
+ * Default fade size: 16 px  (scoped to the element via inline var).
+ * Disable with scroll-fade-none (sets --scroll-fade-mask: none). */
+@utility scroll-fade-x {
+  mask-image: var(--scroll-fade-mask, linear-gradient(to right, transparent, black var(--scroll-fade-size, 16px), black calc(100% - var(--scroll-fade-size, 16px)), transparent));
+}
+@utility scroll-fade-y {
+  mask-image: var(--scroll-fade-mask, linear-gradient(to bottom, transparent, black var(--scroll-fade-size, 16px), black calc(100% - var(--scroll-fade-size, 16px)), transparent));
+}
+@utility scroll-fade-l {
+  mask-image: var(--scroll-fade-mask, linear-gradient(to right, transparent, black var(--scroll-fade-size, 16px)));
+}
+@utility scroll-fade-r {
+  mask-image: var(--scroll-fade-mask, linear-gradient(to left, transparent, black var(--scroll-fade-size, 16px)));
+}
+@utility scroll-fade-t {
+  mask-image: var(--scroll-fade-mask, linear-gradient(to bottom, transparent, black var(--scroll-fade-size, 16px)));
+}
+@utility scroll-fade-b {
+  mask-image: var(--scroll-fade-mask, linear-gradient(to top, transparent, black var(--scroll-fade-size, 16px)));
+}
+@utility scroll-fade-none {
+  --scroll-fade-mask: none;
+}
 @utility h-screen {
   height: 100vh;
   height: 100dvh;

package/src/components/data-display/filter-chip.stories.tsx

@@ -1,38 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-
-import { FilterChip } from "./filter-chip";
-
-const meta = {
-  title: "DataDisplay/FilterChip",
-  component: FilterChip,
-  tags: ["autodocs"],
-  args: {
-    onRemove: () => {},
-  },
-} satisfies Meta<typeof FilterChip>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: { label: "Status: Active" },
-};
-
-export const Editable: Story = {
-  args: { label: "Status: Active", onClick: () => {} },
-};
-
-export const LongLabel: Story = {
-  args: { label: "Created between Jan 1, 2026 and Jul 24, 2026" },
-};
-
-export const Group: Story = {
-  args: { label: "Filters" },
-  render: () => (
-    <div className="flex flex-wrap gap-2">
-      <FilterChip label="Status: Active" onRemove={() => {}} onClick={() => {}} />
-      <FilterChip label="Team: Design" onRemove={() => {}} onClick={() => {}} />
-      <FilterChip label="Archived" onRemove={() => {}} />
-    </div>
-  ),
-};

package/src/components/data-display/filter-chip.tsx

@@ -1,47 +0,0 @@
-import { X } from "lucide-react";
-import type { ReactNode } from "react";
-
-import { cn } from "../../lib/utils";
-
-export interface FilterChipProps {
-  label: ReactNode;
-  onRemove: () => void;
-  onClick?: () => void;
-  className?: string;
-}
-
-/** An applied filter with an optional edit action and an explicit remove action. */
-export function FilterChip({ label, onRemove, onClick, className }: FilterChipProps) {
-  const labelContent = onClick ? (
-    <button
-      type="button"
-      className="focus-visible:ring-ring min-h-9 rounded-full px-3 text-left transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
-      onClick={onClick}
-    >
-      {label}
-    </button>
-  ) : (
-    <span className="flex min-h-9 items-center px-3">{label}</span>
-  );
-
-  return (
-    <span
-      role="group"
-      aria-label={typeof label === "string" ? `${label} filter` : "filter"}
-      className={cn(
-        "border-border bg-secondary text-secondary-foreground inline-flex items-center rounded-full border text-sm font-medium",
-        className,
-      )}
-    >
-      {labelContent}
-      <button
-        type="button"
-        className="text-muted-foreground hover:text-foreground focus-visible:ring-ring mr-1 flex size-9 items-center justify-center rounded-full transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
-        onClick={onRemove}
-        aria-label={`Remove filter: ${typeof label === "string" ? label : "selected filter"}`}
-      >
-        <X className="size-4" aria-hidden />
-      </button>
-    </span>
-  );
-}

package/src/components/forms/entity-select.stories.tsx

@@ -1,65 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { useState } from "react";
-
-import { EntitySelect } from "./entity-select";
-
-const meta = {
-  title: "Forms/EntitySelect",
-  component: EntitySelect,
-  tags: ["autodocs"],
-} satisfies Meta<typeof EntitySelect>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-const options = [
-  { id: "checking", name: "Checking" },
-  { id: "savings", name: "Savings" },
-  { id: "credit-card", name: "Credit Card" },
-];
-
-function EntitySelectPreview() {
-  const [value, setValue] = useState("all");
-  return (
-    <EntitySelect
-      value={value}
-      onValueChange={setValue}
-      options={options}
-      allOptionLabel="All accounts"
-      placeholder="All accounts"
-      label="Account"
-      showLabel
-    />
-  );
-}
-
-export const Default: Story = {
-  args: {
-    value: "all",
-    onValueChange: () => {},
-    options,
-  },
-  render: () => <EntitySelectPreview />,
-};
-
-export const Loading: Story = {
-  args: {
-    value: "all",
-    onValueChange: () => {},
-    options: [],
-    isLoading: true,
-    label: "Account",
-    showLabel: true,
-  },
-};
-
-export const Empty: Story = {
-  args: {
-    value: "all",
-    onValueChange: () => {},
-    options: [],
-    label: "Account",
-    showLabel: true,
-    emptyLabel: "No accounts available",
-  },
-};

package/src/components/forms/entity-select.tsx

@@ -1,79 +0,0 @@
-import { useId } from "react";
-
-import { Label } from "../primitives/label";
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./select";
-
-export interface EntitySelectOption {
-  id: string;
-  name: string;
-}
-
-export interface EntitySelectProps {
-  value: string;
-  onValueChange: (value: string) => void;
-  options: EntitySelectOption[];
-  isLoading?: boolean;
-  placeholder?: string;
-  label?: string;
-  showLabel?: boolean;
-  allOptionLabel?: string;
-  emptyLabel?: string;
-  className?: string;
-}
-
-/** Labeled `Select` over an `{ id, name }[]` list, with loading/empty states and an "all" option. */
-export function EntitySelect({
-  value,
-  onValueChange,
-  options,
-  isLoading = false,
-  placeholder = "All",
-  label = "Filter",
-  showLabel = false,
-  allOptionLabel = "All",
-  emptyLabel = "No options available",
-  className,
-}: EntitySelectProps) {
-  const id = useId();
-
-  const selectElement = (
-    <Select
-      name={label}
-      value={value}
-      onValueChange={(v: string | null) => v != null && onValueChange(v)}
-    >
-      <SelectTrigger id={id} className={className}>
-        <SelectValue placeholder={placeholder} />
-      </SelectTrigger>
-      <SelectContent className="max-h-[250px] overflow-y-auto">
-        <SelectItem value="all">{allOptionLabel}</SelectItem>
-        {isLoading ? (
-          <SelectItem value="loading" disabled>
-            Loading...
-          </SelectItem>
-        ) : options.length === 0 ? (
-          <SelectItem value="empty" disabled>
-            {emptyLabel}
-          </SelectItem>
-        ) : (
-          options.map((option) => (
-            <SelectItem key={option.id} value={option.id}>
-              {option.name}
-            </SelectItem>
-          ))
-        )}
-      </SelectContent>
-    </Select>
-  );
-
-  if (showLabel) {
-    return (
-      <div className="space-y-2">
-        <Label htmlFor={id}>{label}</Label>
-        {selectElement}
-      </div>
-    );
-  }
-
-  return selectElement;
-}