@upbound/monarch-blocks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Upbound
+
+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,58 @@
+# @upbound/monarch-blocks
+
+Upbound's design system — composed components: `Chart`, `DataTable`, `FilterBar`, `CelFilterBar`, `ChatInterface`,
+`Timeline`, and more. Built on [`@upbound/monarch-core`](https://www.npmjs.com/package/@upbound/monarch-core)'s
+primitives, with real dependencies of their own (charting, table state, CEL filter expression compiling) that
+`monarch-core` deliberately stays free of.
+
+Kept as a separate package from `monarch-core` on purpose: installing it always pulls in `@upbound/monarch-core` as a
+real dependency, but installing `monarch-core` alone never pulls in this package's heavier dependency tree.
+
+## Install
+
+```bash
+npm install @upbound/monarch-blocks
+```
+
+Peer dependencies: `react` and `react-dom` (`^18.3.0 || ^19.0.0`), `tailwindcss` (`^4.0.0`). `@upbound/monarch-core`
+installs automatically as a transitive dependency.
+
+## Set up the theme
+
+This package ships no CSS of its own — it reuses `@upbound/monarch-core`'s tokens and utility classes. Set up
+`monarch-core`'s theme as documented in
+[its README](https://www.npmjs.com/package/@upbound/monarch-core#set-up-the-theme); `monarch-blocks` needs the same
+`@import` and `@source` lines, with one addition — extend the `@source` glob to cover this package's compiled files too:
+
+```css
+@import 'tailwindcss';
+@import '@upbound/monarch-core/theme.css';
+@source '../../node_modules/@upbound/monarch-core/dist/*.js';
+@source '../../node_modules/@upbound/monarch-blocks/dist/*.js';
+```
+
+(Path assumes a Next.js `--src-dir` layout — see `@upbound/monarch-core`'s README for why `dist/*.js`, not a recursive
+glob, and why the path climbs two directories.)
+
+## Use a component
+
+```tsx
+import { DataTable } from '@upbound/monarch-blocks';
+```
+
+Or import a single component's own subpath, same as `monarch-core`:
+
+```tsx
+import { DataTable } from '@upbound/monarch-blocks/data-table';
+```
+
+### Server Components
+
+Same caveat as `monarch-core`: the root barrel bundles every component into one file and is a client boundary
+unconditionally. Import a component's own subpath if you need it in a context where that matters.
+
+## Not part of the shadcn registry
+
+Unlike `@upbound/monarch-core`, these components are **not** available through `npx shadcn add @monarch/...` — the
+registry intentionally sources from `monarch-core` only, so a consumer using the shadcn CLI path never pulls in this
+package's heavier dependencies. npm install is the only distribution channel for `monarch-blocks`.

package/dist/cel-filter-bar.d.ts

@@ -0,0 +1,187 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { k as CompileResult, t as CelValidationMeta, d as CelFilterCondition, f as CelFilterSchema, V as ValidationIssue, g as CelFilterTree, P as PillActiveSurface, u as CelFilterType, h as CelOperator, v as CelFilterShape, C as CelColumnDefinition, w as CelEmitOn, D as DateCelValue, M as MapKeyCelValue, l as MultiTextCelValue, m as RelativeDurationPreset, c as CelFilterBarProps } from './types-BULiU2qC.js';
+export { a as CelColumnOption, b as CelConditionValue, e as CelFilterGroup, i as CelRestrictedOptionSelectPayload, j as CheckboxCelValue, R as RadioCelValue, n as isCelFilterCondition, o as isCelFilterGroup, p as isCheckboxCelValue, q as isDateCelValue, r as isMapKeyCelValue, s as isMultiTextCelValue } from './types-BULiU2qC.js';
+
+/**
+ * Applies draft/commit display rules to a raw compile result.
+ *
+ * Validation timing: a condition's issues are surfaced on its pill and in the
+ * global panel only once it has been committed (popover closed) and is not
+ * currently being edited. Group-level issues (e.g. nesting depth) always show.
+ *
+ * `isEmitReady` on the returned object is always `false` here — it is a
+ * placeholder that `CelFilterBar` overrides via `computeIsEmitReady` before
+ * calling `onCompileResultChange`. This is the single source of truth for the gate.
+ */
+
+declare function applyDisplayRules(raw: CompileResult, meta: CelValidationMeta): CompileResult;
+
+/**
+ * Validates a single condition against the provided schema. Returns an empty
+ * array when the condition is complete and compilable.
+ */
+declare function validateCondition(condition: CelFilterCondition, schema: CelFilterSchema): ValidationIssue[];
+
+type ComputeIsEmitReadyMeta = {
+    activeSurface: PillActiveSurface | null;
+    committedConditionIds: Set<string>;
+};
+/**
+ * Gates API emission while a commit-mode condition is mid-edit. Only the
+ * actively edited condition matters — one popover at a time.
+ */
+declare function computeIsEmitReady(raw: CompileResult, editingConditionId: string | null, schema: CelFilterSchema, tree: CelFilterTree, meta: ComputeIsEmitReadyMeta): boolean;
+
+/**
+ * Walks the tree, joins root children with ` && `, and emits a CEL string when
+ * everything is complete and valid. An empty root compiles to `""` with status
+ * `valid` (the API treats an empty filter as no filter).
+ */
+declare function compileCelFilterTree(tree: CelFilterTree, schema: CelFilterSchema): CompileResult;
+
+/**
+ * Instant helpers for the CEL date filter.
+ *
+ * Stored values are RFC3339 UTC strings, and everything here manipulates them as
+ * text rather than through `Date`, so a filter can never drift into the viewer's
+ * local timezone. Tables render timestamps in UTC, so a UTC filter is what
+ * agrees with the times shown in the table.
+ */
+/** Which end of a day/minute an instant represents. */
+type DateBoundary = 'start' | 'end';
+declare function calendarDayStartInstant(instant: string): string;
+/**
+ * True when the date portion names a day that exists. `Date` rolls impossible
+ * days over silently — Feb 31 becomes Mar 3 rather than failing — so a
+ * round-trip through UTC is what separates a real day from a rolled-over one.
+ */
+declare function isRealCalendarDay(instant: string): boolean;
+/** Reads the `HH:mm` an `input[type="time"]` displays for a stored instant. */
+declare function readTimeOfDay(instant: string | undefined): string;
+/** Replaces the time portion of an instant. Seconds are zeroed — the input is minute-granular. */
+declare function withTimeOfDay(instant: string, timeOfDay: string): string;
+/**
+ * Stamps a picked calendar day as a UTC instant. The picker hands back a local
+ * `Date` whose Y/M/D is the day that was clicked; that day is stored as the
+ * matching UTC day so the filter lines up with the UTC timestamps in the table.
+ */
+declare function formatCalendarDateUtc(date: Date, boundary: DateBoundary): string;
+/** Parses a stored RFC3339 string back into a local Date carrying the calendar day. */
+declare function parseCalendarDate(value: string | undefined): Date | undefined;
+/**
+ * Locale date for display, plus the UTC time when the instant carries a
+ * user-picked one. `locale` defaults to the runtime's own locale (matching
+ * plain `toLocaleDateString()`) — callers rendered during SSR should pass a
+ * fixed locale explicitly (see `cel-filter-bar.tsx`'s `useMounted()` gating)
+ * so the server-rendered/first-paint value doesn't hydration-mismatch against
+ * the viewer's actual browser locale.
+ */
+declare function formatInstantLabel(instant: string | undefined, { withTime, locale }?: {
+    withTime?: boolean;
+    locale?: string;
+}): string;
+
+/**
+ * Operator metadata and CEL fragment generation.
+ *
+ * This is the single place that knows how `condition.operator` + value map to CEL
+ * output. UI components never hand-write CEL — they read/write tree state and the
+ * compiler walks it through here.
+ */
+
+/**
+ * Returns the operators allowed for a column. `allowedOperators` on a column
+ * definition overrides the default set derived from its filter type.
+ */
+declare function getAllowedOperators(columnDef?: CelColumnDefinition): CelOperator[];
+declare function isDateRelativeOperator(operator: CelOperator): boolean;
+/** True for the date operators that match a whole calendar day and so take no time. */
+declare function isDateWindowOperator(operator: CelOperator): boolean;
+/** True for the date operators whose value is a `range` rather than an `instant`. */
+declare function isDateRangeOperator(operator: CelOperator): boolean;
+/**
+ * Which day boundary a date comparator compares against, and therefore the time
+ * its input prefills with until the user edits it.
+ */
+declare function dateBoundaryForOperator(operator: CelOperator): DateBoundary;
+declare function resolveColumnDefinition(condition: Pick<CelFilterCondition, 'columnId'>, schema: CelFilterSchema): CelColumnDefinition | undefined;
+/** Resolves the value/operator shape for a condition, or `undefined` for an unknown column. */
+declare function resolveFilterShape(condition: Pick<CelFilterCondition, 'columnId' | 'value'>, schema: CelFilterSchema): CelFilterShape | undefined;
+declare function getOperatorLabel(operator: CelOperator): string;
+declare function getQuantifierLabel(quantifier: 'any' | 'all'): string;
+declare function allowsMultipleConditions(filterType: CelFilterType): boolean;
+declare function getDefaultOperator(filterType: CelFilterType): CelOperator;
+/**
+ * Applies the minimal value-retention rules when the operator changes on an
+ * existing condition. Returns a new condition; does not mutate the input.
+ *
+ * For dates, the clearing rules here are the enforcement half of the date state
+ * machine the date editor implements: clear when the value shape changes (range
+ * operators vs single-instant ones), or when a relative value would become
+ * illegal under `is`/`is_not`, and drop a picked time when moving to a
+ * whole-day operator. Keep both in sync.
+ */
+declare function applyOperatorChange(condition: CelFilterCondition, newOperator: CelOperator, shape: CelFilterShape | undefined): CelFilterCondition;
+/** Maps parsed CEL aliases back to schema column ids when building the filter tree. */
+declare function denormalizeColumnIdWithReservedNames(columnId: string): string;
+
+/**
+ * Escapes a user-provided string literal for safe embedding inside a CEL
+ * double-quoted string. Callers wrap the result in `"..."` at the use site
+ * (e.g. `column == "${escapeCelString(value)}"`).
+ *
+ * CEL generated output uses double-quoted strings only, so single quotes are
+ * left untouched.
+ */
+declare function escapeCelString(input: string): string;
+/** Convenience helper that escapes and wraps a value in double quotes. */
+declare function celStringLiteral(input: string): string;
+
+/** Generates a stable unique id, falling back when `crypto.randomUUID` is unavailable. */
+declare function createCelNodeId(): string;
+/** Creates an empty tree whose root is a depth-0 `and` group with no children. */
+declare function createEmptyCelFilterTree(): CelFilterTree;
+type CreateDefaultConditionParams = {
+    schema: CelFilterSchema;
+    columnId: string;
+};
+/**
+ * Creates a new condition with the default operator for its column and an
+ * undefined value (filled in by the user in the popover).
+ */
+declare function createDefaultCondition({ schema, columnId }: CreateDefaultConditionParams): CelFilterCondition;
+/** Appends a condition to the root group's children. */
+declare function appendCondition(tree: CelFilterTree, condition: CelFilterCondition): CelFilterTree;
+/** Replaces a root-level condition by id, applying `updater` to the existing condition. Root-level only — v1's UI never produces nested groups. */
+declare function replaceCondition(tree: CelFilterTree, conditionId: string, updater: (condition: CelFilterCondition) => CelFilterCondition): CelFilterTree;
+/** Removes a root-level condition by id. */
+declare function removeConditionById(tree: CelFilterTree, conditionId: string): CelFilterTree;
+
+/** Upserts (or unions, for checkbox) an externally-provided value into the tree by column type. */
+declare function mergeContextualIntoCelTree(tree: CelFilterTree, schema: CelFilterSchema, columnId: string, values: string[]): CelFilterTree;
+
+declare function isMultiTextColumn(columnId: string, schema: CelFilterSchema): boolean;
+/** Returns when a column's valid value may be emitted; explicit `emitOn` overrides filterType defaults. */
+declare function getColumnEmitOn(columnDef: CelColumnDefinition): CelEmitOn;
+
+/** Relative when a preset is set; preset and absolute fields are mutually exclusive. */
+declare function isRelativeDateCelValue(value: DateCelValue): boolean;
+declare function readDateCelValue(value: unknown): DateCelValue;
+declare function readMapKeyCelValue(value: unknown): MapKeyCelValue;
+declare function readMultiTextCelValue(value: unknown): MultiTextCelValue;
+
+/**
+ * Shared limits and defaults for the CEL filter builder. Values mirror the API
+ * constraints (`maxNestingDepth = 50`, `maxRegexLen = 1000`).
+ */
+
+/**
+ * Trusted relative date presets emitted as fixed `duration(...)` literals in
+ * compiled CEL. Hours only — `duration()` rejects a `d` unit.
+ */
+declare const RELATIVE_DURATION_PRESET_VALUES: readonly ["24h", "168h", "720h"];
+declare function isRelativeDurationPreset(value: string): value is RelativeDurationPreset;
+
+declare function CelFilterBar({ tree, onChange, schema, onCompileResultChange, onRestrictedOptionSelect, showClearButton, className, }: CelFilterBarProps): react_jsx_runtime.JSX.Element;
+
+export { CelColumnDefinition, CelFilterBar, CelFilterBarProps, CelFilterCondition, CelFilterSchema, CelFilterTree, CelOperator, CompileResult, DateCelValue, MapKeyCelValue, MultiTextCelValue, PillActiveSurface, RELATIVE_DURATION_PRESET_VALUES, RelativeDurationPreset, ValidationIssue, allowsMultipleConditions, appendCondition, applyDisplayRules, applyOperatorChange, calendarDayStartInstant, celStringLiteral, compileCelFilterTree, computeIsEmitReady, createCelNodeId, createDefaultCondition, createEmptyCelFilterTree, dateBoundaryForOperator, denormalizeColumnIdWithReservedNames, escapeCelString, formatCalendarDateUtc, formatInstantLabel, getAllowedOperators, getColumnEmitOn, getDefaultOperator, getOperatorLabel, getQuantifierLabel, isDateRangeOperator, isDateRelativeOperator, isDateWindowOperator, isMultiTextColumn, isRealCalendarDay, isRelativeDateCelValue, isRelativeDurationPreset, mergeContextualIntoCelTree, parseCalendarDate, readDateCelValue, readMapKeyCelValue, readMultiTextCelValue, readTimeOfDay, removeConditionById, replaceCondition, resolveColumnDefinition, resolveFilterShape, validateCondition, withTimeOfDay };