@flytedan/flytebot-design-system 0.32.0 → 0.34.0

package/dist/index.d.cts

@@ -1188,17 +1188,30 @@ type FilterValue<F extends FilterField> = F extends FilterFieldText ? string : F
 interface FilterBarProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onChange"> {
     /** Every filter a consumer can add. Order here is the order in the "add filter" list. */
     fields: FilterField[];
-    /** Straight off useServerTable — a value of undefined/""/false reads as "not set",
+    /** The applied filters, and the single source of truth for them: FilterBar keeps no
+     *  copy. Straight off useServerTable — a value of undefined/""/false reads as "not set",
      *  same convention that hook already uses for activeFilterCount. multiSelect/range/
-     *  date values are objects instead (see isFieldSet). */
+     *  date values are objects instead (see isFieldSet). Every edit, and every paste that
+     *  settles later, is computed from this prop as it stands at that moment; a panel seeds
+     *  itself from it when it opens, and follows it if it changes while open. */
     filters: Record<string, unknown>;
     /** Fires on every value edit. Maps 1:1 onto useServerTable's setFilter(id, value).
      *  FilterBar only ever calls this with a COMPLETE, valid value for the field — an
-     *  emptied selection, a one-sided date range, an invalid numeric range or a cleared
-     *  bound go through onFilterRemove (or nothing) instead. */
+     *  emptied selection, a one-sided date range, an invalid numeric range, number text
+     *  that isn't a valid value, or a cleared bound go through onFilterRemove (or nothing,
+     *  when the filter isn't set) instead.
+     *
+     *  FilterBar is a controlled component: apply this to your state synchronously, so the
+     *  next render passes the new `filters`. Never apply it inside `startTransition` or
+     *  after a delay; React's rule for controlled inputs applies here too. Number fields
+     *  emit on every keystroke that leaves them valid, so defer the EXPENSIVE work instead:
+     *  debounce the request this triggers, or read the filters through useDeferredValue. A
+     *  host that keeps filters in the URL keeps them in memory as the source of truth and
+     *  syncs the URL from that. */
     onFilterChange: (key: string, value: unknown) => void;
     /** Fires when a chip's × is clicked, or when an edit leaves a field with no valid
-     *  value. Maps 1:1 onto useServerTable's clearFilter(id). */
+     *  value; never for a key that isn't set in `filters`. Maps 1:1 onto useServerTable's
+     *  clearFilter(id). Apply it synchronously, exactly like onFilterChange. */
     onFilterRemove: (key: string) => void;
     /** Which edge the "add filter" popover aligns to. Default "left" — the trigger sits
      *  at the end of a left-to-right chip row, so its menu opens under its left edge. */
@@ -1236,6 +1249,11 @@ declare function validateFilterValue(field: FilterField, value: unknown): Filter
  * values, only the transient "which field's popover/input is open right now" UI state
  * (`panel`), the same way SortMenu holds `open` but never sort state itself.
  *
+ * It is a standard controlled component. `filters` is the single source of truth, and
+ * the host applies onFilterChange/onFilterRemove to it synchronously (never inside
+ * `startTransition`, never after a timeout), deferring only the expensive query that the
+ * filters drive, with a debounce or useDeferredValue.
+ *
  * Every floating surface — a field's edit panel and the "add filter" menu — is a real
  * Popover (or Menu-in-a-Popover) from this kit's own actions module: viewport clamping,
  * nested-layer handling, Escape, and focus-return-to-the-chip all come from there, so

package/dist/index.d.ts

@@ -1188,17 +1188,30 @@ type FilterValue<F extends FilterField> = F extends FilterFieldText ? string : F
 interface FilterBarProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onChange"> {
     /** Every filter a consumer can add. Order here is the order in the "add filter" list. */
     fields: FilterField[];
-    /** Straight off useServerTable — a value of undefined/""/false reads as "not set",
+    /** The applied filters, and the single source of truth for them: FilterBar keeps no
+     *  copy. Straight off useServerTable — a value of undefined/""/false reads as "not set",
      *  same convention that hook already uses for activeFilterCount. multiSelect/range/
-     *  date values are objects instead (see isFieldSet). */
+     *  date values are objects instead (see isFieldSet). Every edit, and every paste that
+     *  settles later, is computed from this prop as it stands at that moment; a panel seeds
+     *  itself from it when it opens, and follows it if it changes while open. */
     filters: Record<string, unknown>;
     /** Fires on every value edit. Maps 1:1 onto useServerTable's setFilter(id, value).
      *  FilterBar only ever calls this with a COMPLETE, valid value for the field — an
-     *  emptied selection, a one-sided date range, an invalid numeric range or a cleared
-     *  bound go through onFilterRemove (or nothing) instead. */
+     *  emptied selection, a one-sided date range, an invalid numeric range, number text
+     *  that isn't a valid value, or a cleared bound go through onFilterRemove (or nothing,
+     *  when the filter isn't set) instead.
+     *
+     *  FilterBar is a controlled component: apply this to your state synchronously, so the
+     *  next render passes the new `filters`. Never apply it inside `startTransition` or
+     *  after a delay; React's rule for controlled inputs applies here too. Number fields
+     *  emit on every keystroke that leaves them valid, so defer the EXPENSIVE work instead:
+     *  debounce the request this triggers, or read the filters through useDeferredValue. A
+     *  host that keeps filters in the URL keeps them in memory as the source of truth and
+     *  syncs the URL from that. */
     onFilterChange: (key: string, value: unknown) => void;
     /** Fires when a chip's × is clicked, or when an edit leaves a field with no valid
-     *  value. Maps 1:1 onto useServerTable's clearFilter(id). */
+     *  value; never for a key that isn't set in `filters`. Maps 1:1 onto useServerTable's
+     *  clearFilter(id). Apply it synchronously, exactly like onFilterChange. */
     onFilterRemove: (key: string) => void;
     /** Which edge the "add filter" popover aligns to. Default "left" — the trigger sits
      *  at the end of a left-to-right chip row, so its menu opens under its left edge. */
@@ -1236,6 +1249,11 @@ declare function validateFilterValue(field: FilterField, value: unknown): Filter
  * values, only the transient "which field's popover/input is open right now" UI state
  * (`panel`), the same way SortMenu holds `open` but never sort state itself.
  *
+ * It is a standard controlled component. `filters` is the single source of truth, and
+ * the host applies onFilterChange/onFilterRemove to it synchronously (never inside
+ * `startTransition`, never after a timeout), deferring only the expensive query that the
+ * filters drive, with a debounce or useDeferredValue.
+ *
  * Every floating surface — a field's edit panel and the "add filter" menu — is a real
  * Popover (or Menu-in-a-Popover) from this kit's own actions module: viewport clamping,
  * nested-layer handling, Escape, and focus-return-to-the-chip all come from there, so