@ponti-studios/ui 0.4.4 → 0.7.0

package/src/components/filters/search-filter-bar.tsx

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+
+import { cn } from '../../lib/utils';
+import { ActiveFiltersBar, type ActiveFilter } from './active-filters-bar';
+
+export interface SearchFilterBarProps {
+  activeFilters: ActiveFilter[];
+  onClearAll?: () => void;
+  search?: ReactNode;
+  filters?: ReactNode[];
+  results?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+  filterItemClassName?: string;
+}
+
+export function SearchFilterBar({
+  activeFilters,
+  onClearAll,
+  search,
+  filters,
+  results,
+  children,
+  className,
+  filterItemClassName = 'sm:w-48',
+}: SearchFilterBarProps) {
+  return (
+    <div className={cn('flex flex-col gap-4', className)}>
+      <div className="flex flex-col gap-3 lg:flex-row lg:items-center">
+        {search ? <div className="flex-1">{search}</div> : null}
+
+        {filters?.map((filter, index) => (
+          <div key={index} className={filterItemClassName}>
+            {filter}
+          </div>
+        ))}
+
+        {results ? (
+          <div className="self-start lg:ml-auto lg:self-auto">{results}</div>
+        ) : null}
+
+        {children}
+      </div>
+
+      <ActiveFiltersBar filters={activeFilters} onClearAll={onClearAll} />
+    </div>
+  );
+}

package/src/components/forms/index.ts

@@ -6,10 +6,10 @@ export { DateMonthSelect, getCurrentMonthYear } from "./date-month-select";
 export type { DateMonthSelectProps } from "./date-month-select";
 export { DropZone } from "./drop-zone";
 export type { DropZoneProps } from "./drop-zone";
-export { EntitySelect } from "./entity-select";
-export type { EntitySelectOption, EntitySelectProps } from "./entity-select";
 export { Field } from "./field";
 export type { FieldProps } from "./field";
+export { FilterSelect } from "../filters/filter-select";
+export type { FilterSelectOption, FilterSelectProps } from "../filters/filter-select";
 export { GroupBySelect } from "./group-by-select";
 export type { GroupBySelectProps } from "./group-by-select";
 export { Input } from "./input";

package/src/components/forms/input.tsx

@@ -8,7 +8,7 @@ function Input({ className, type, ...props }: React.ComponentProps<"input">) {
       type={type}
       data-slot="input"
       className={cn(
-        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground bg-background focus-visible:ring-ring border-input h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base transition-colors file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground bg-background text-foreground focus-visible:ring-ring border-input h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base transition-colors file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
         "aria-invalid:ring-destructive/20 aria-invalid:border-destructive",
         className,
       )}

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",
-  },
-};