@gridkitjs/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blagoja Blazhevski
+
+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,34 @@
+# @gridkitjs/core
+
+Framework-agnostic data-grid logic — column resolution, alignment and sizing.
+Plain TypeScript, no DOM required, so it is reusable from any framework
+adapter.
+
+> **Early development.** The API is still moving and may break between minor
+> versions.
+
+```bash
+pnpm add @gridkitjs/core
+```
+
+```ts
+import { defineColumnsFromRows, resolveColumnWidths } from "@gridkitjs/core";
+
+const columns = defineColumnsFromRows(rows);
+const resolved = resolveColumnWidths(columns, sizing, {
+  sizes: { width: 160 },
+  resizable: true,
+});
+```
+
+Each entry in `resolved` pairs a column with everything needed to render it —
+`width`, `label`, `resizable` and `alignment` — so an adapter renders what it
+is handed rather than re-deriving it.
+
+For React, see [`@gridkitjs/react`](https://www.npmjs.com/package/@gridkitjs/react).
+
+Full documentation: [github.com/blagojablazhevski/gridkit](https://github.com/blagojablazhevski/gridkit#readme)
+
+## License
+
+MIT © Blagoja Blazhevski

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Values a cell shows as-is instead of being drilled into. Arrays and `Date`s
+ * are cell values rather than groups of columns, and `null` cannot be
+ * introspected, so all three end a path.
+ */
+type LeafValue = bigint | boolean | number | string | symbol | null | undefined | Date | readonly unknown[] | ((...args: never[]) => unknown);
+/** Keys of `T` holding a leaf value — the only ones a path may end on. */
+type LeafKey<T> = {
+    [K in keyof T & string]: NonNullable<T[K]> extends LeafValue ? K : never;
+}[keyof T & string];
+/**
+ * Every addressable field of `Row`, one level deep: `"Id"` for a flat field,
+ * `"Application.Id"` for a leaf inside a nested object. A nested object
+ * contributes only its leaf children, never itself and never anything deeper.
+ */
+type FieldPath<Row> = {
+    [K in keyof Row & string]: NonNullable<Row[K]> extends LeafValue ? K : `${K}.${LeafKey<NonNullable<Row[K]>>}`;
+}[keyof Row & string];
+/**
+ * The value type of a column's cells. This package is framework-agnostic so it
+ * defaults to `string`;
+ */
+type ColumnType = "dateTime" | "date" | "time" | "number" | "string" | "boolean" | "decimal" | "currency" | "percent";
+type ColumnAlignment = "left" | "center" | "right";
+/**
+ * @typeParam Header - What a header renders to. This package is
+ * framework-agnostic so it defaults to `string`; `@gridkitjs/react` binds it to
+ * `ReactNode` so a header callback can return JSX.
+ */
+interface ColumnDefinition<Row, Header = string> {
+    /**
+     * Path to this cell's value: a key of `Row`, or `"Parent.Child"` for a leaf
+     * one level inside a nested object. Any string still compiles — the union
+     * exists to drive autocomplete, not to lock the grid down.
+     */
+    field: FieldPath<Row> | (string & {});
+    /**
+     * Stable identity for state keyed by this column. Defaults to `field`, which
+     * is unique in the common case but need not be — two columns may render the
+     * same field differently.
+     */
+    id?: string;
+    /** Header content, or a function returning it at render time. */
+    header?: Header | (() => Header) | undefined;
+    /**
+     * The value type of this column's cells. This package is framework-agnostic so it
+     * defaults to `string`;
+     */
+    type?: ColumnType;
+    /**
+     * Alignment of this column's cells. This package is framework-agnostic so it
+     * defaults to `left` (`right` for numbers);
+     */
+    alignment?: ColumnAlignment;
+    /**
+     * Width in px this column starts at. A user resize overrides it for as long
+     * as that resize lives in the sizing state.
+     */
+    width?: number;
+    /** Lower bound a resize may not drag below. */
+    minWidth?: number;
+    /** Upper bound a resize may not drag above. */
+    maxWidth?: number;
+    /** Whether this column can be resized, overriding the grid-level default. */
+    resizable?: boolean;
+}
+/**
+ * Widths the user has changed, keyed by column id. Holding only what changed —
+ * rather than every width — means a `width` edited in the column definition
+ * still takes effect, and resetting is discarding the state.
+ */
+type ColumnSizingState = Readonly<Record<string, number>>;
+/** Sizes used for a column that does not specify its own. */
+interface ColumnSizeDefaults {
+    width: number;
+    minWidth: number;
+    maxWidth: number;
+}
+/** The bounds a column's width is held between, resolved once from both. */
+interface ColumnConstraints {
+    minWidth: number;
+    maxWidth: number;
+}
+/**
+ * Grid-level defaults a column falls back to when it does not set its own.
+ * Sizes are grouped so the rest of the grid's defaults have somewhere to go.
+ */
+interface ColumnResolveOptions {
+    sizes?: Partial<ColumnSizeDefaults> | undefined;
+    /** Whether columns are resizable, unless a column says otherwise. */
+    resizable?: boolean | undefined;
+}
+/**
+ * A column paired with everything it takes to render it. Each field is a
+ * decision made once here rather than in each adapter, so a second framework
+ * binding renders identically without repeating the logic.
+ */
+interface ResolvedColumn<Row, Header = string> {
+    column: ColumnDefinition<Row, Header>;
+    id: string;
+    width: number;
+    /**
+     * Whether `width` came from the sizing state rather than the column
+     * definition — that is, whether the user set it. Auto-fit leaves these
+     * columns alone so that resizing one does not undo itself.
+     */
+    sized: boolean;
+    /**
+     * What the header shows: the column's own `header`, or a label read off the
+     * field path. `string` is in the union because that fallback is text
+     * whatever `Header` is bound to.
+     */
+    label: Header | string;
+    /** Whether this column can be resized, after the grid-level default. */
+    resizable: boolean;
+    /** How this column's cells align, after falling back to its type. */
+    alignment: ColumnAlignment;
+}
+/**
+ * A resize in progress. It captures its constraints up front so that applying
+ * a pointer position is arithmetic on numbers alone — no column, no DOM.
+ */
+interface ColumnResizeSession {
+    readonly columnId: string;
+    readonly startWidth: number;
+    readonly startPosition: number;
+    readonly constraints: ColumnConstraints;
+}
+/**
+ * Reports a user resize. `phase` separates the two audiences: `"move"` fires
+ * continuously for live feedback, `"end"` once on release — the one to persist.
+ */
+interface ColumnResizeEvent {
+    readonly columnId: string;
+    readonly width: number;
+    readonly sizing: ColumnSizingState;
+    readonly phase: "move" | "end";
+}
+
+/**
+ * How a column of `type` aligns by default. Numeric types align right so that
+ * their digits line up by place value; everything else reads from the left.
+ */
+declare function alignmentForType(type: ColumnType): ColumnAlignment;
+/**
+ * Derives one column per field across `rows`, in the order each field is first
+ * seen — so a key that only appears in a later row still gets a column,
+ * appended at the end. Nested objects contribute their non-object properties
+ * as `"Parent.Child"`; anything deeper is skipped, as is the nested object
+ * itself.
+ *
+ * Order follows `Object.entries`, which lists integer-like keys first
+ * regardless of the order they were written in.
+ */
+declare function defineColumnsFromRows<Row>(rows: readonly Row[]): readonly ColumnDefinition<Row>[];
+/**
+ * The key state about a column is stored under, and the key it renders with.
+ * Every such lookup goes through here so the two can never disagree.
+ */
+declare function getColumnId<Row>(column: ColumnDefinition<Row, unknown>): string;
+/**
+ * What a column's header shows: its own `header`, called first if it is a
+ * function, or else a label read off the field path — `"Application.Id"`
+ * reading as `"Application Id"`.
+ */
+declare function resolveColumnLabel<Row, Header>(column: ColumnDefinition<Row, Header>): Header | string;
+/**
+ * Accesses a value at a dotted path, e.g. `foo.bar.baz`.
+ *
+ * @param obj The object to access
+ * @param path Path to the value, e.g. `"foo.bar"`
+ * @returns The value at `path`, or `undefined` if it doesn't exist
+ */
+declare function accessDotted(obj: unknown, path: string): unknown;
+
+/**
+ * Applied to any column that does not size itself. The minimum is a width a
+ * header stays legible at rather than a measured value — a column dragged
+ * narrower than this reads as a rendering fault.
+ */
+declare const DEFAULT_COLUMN_SIZES: ColumnSizeDefaults;
+/** How far one arrow key press moves a column edge. */
+declare const KEYBOARD_STEP = 10;
+/**
+ * The bounds `column` may be sized between. Resolved in one place so that a
+ * drag, a clamp and an auto-fit cannot disagree about a column's limits.
+ */
+declare function resolveColumnConstraints<Row>(column: ColumnDefinition<Row, unknown>, defaults?: Partial<ColumnSizeDefaults>): ColumnConstraints;
+/** Holds `width` within `constraints`. */
+declare function clampColumnWidth(width: number, constraints: ColumnConstraints): number;
+/**
+ * Pairs each column with everything needed to render it — the width it sits
+ * at, the label its header shows, whether it may be resized and how its cells
+ * align. Widths take the first of the sizing state, the column's own `width`,
+ * and the default, then clamp.
+ *
+ * The sizing state winning means a user's drag outlives a re-render; a column
+ * absent from it still tracks a `width` edited in the definition.
+ */
+declare function resolveColumnWidths<Row, Header>(columns: readonly ColumnDefinition<Row, Header>[], sizing: ColumnSizingState, options?: ColumnResolveOptions): readonly ResolvedColumn<Row, Header>[];
+declare function totalColumnWidth<Row, Header>(resolved: readonly ResolvedColumn<Row, Header>[]): number;
+/**
+ * Opens a resize. The session captures its constraints and starting point up
+ * front, so applying a pointer position later is arithmetic on numbers alone —
+ * which is what keeps the drag testable without a DOM.
+ *
+ * @param startPosition Where the pointer went down, on the axis being dragged.
+ */
+declare function beginColumnResize<Row>(column: ColumnDefinition<Row, unknown>, startWidth: number, startPosition: number, defaults?: Partial<ColumnSizeDefaults>): ColumnResizeSession;
+/**
+ * The width the dragged column takes with the pointer at `position`. The delta
+ * is signed, so a right-to-left adapter negates it and nothing else changes.
+ */
+declare function applyColumnResize(session: ColumnResizeSession, position: number): number;
+/**
+ * Grows columns proportionally until they fill `availableWidth`.
+ *
+ * Growth only: columns that already meet or exceed the width are returned
+ * untouched, so a container too narrow for them scrolls rather than crushing
+ * them. Columns the user has sized are left at that width and the rest share
+ * what is left, so dragging one column does not rubber-band it back.
+ */
+declare function fitColumnsToWidth<Row, Header>(resolved: readonly ResolvedColumn<Row, Header>[], availableWidth: number, defaults?: Partial<ColumnSizeDefaults>): readonly ResolvedColumn<Row, Header>[];
+/**
+ * The width a column needs to show `measuredWidth` of content.
+ *
+ * `padding` is an allowance on top of the measurement, since a column sized to
+ * exactly its content can still round down into an ellipsis.
+ */
+declare function sizeColumnToContent(measuredWidth: number, constraints: ColumnConstraints, padding?: number): number;
+
+export { type ColumnAlignment, type ColumnConstraints, type ColumnDefinition, type ColumnResizeEvent, type ColumnResizeSession, type ColumnResolveOptions, type ColumnSizeDefaults, type ColumnSizingState, type ColumnType, DEFAULT_COLUMN_SIZES, type FieldPath, KEYBOARD_STEP, type ResolvedColumn, accessDotted, alignmentForType, applyColumnResize, beginColumnResize, clampColumnWidth, defineColumnsFromRows, fitColumnsToWidth, getColumnId, resolveColumnConstraints, resolveColumnLabel, resolveColumnWidths, sizeColumnToContent, totalColumnWidth };

package/dist/index.js

@@ -0,0 +1,195 @@
+// src/util/grid.ts
+function isNested(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+function getType(value) {
+  if (value instanceof Date) return "dateTime";
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "bigint") return "number";
+  if (typeof value === "symbol") return "string";
+  return "string";
+}
+function alignmentForType(type) {
+  switch (type) {
+    case "number":
+    case "decimal":
+    case "currency":
+    case "percent":
+      return "right";
+    default:
+      return "left";
+  }
+}
+function getAlignment(value) {
+  return alignmentForType(getType(value));
+}
+function defineColumnsFromRows(rows) {
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  function add(field, value) {
+    if (seen.has(field)) {
+      return;
+    }
+    seen.add(field);
+    columns.push({
+      field,
+      type: getType(value),
+      alignment: getAlignment(value)
+    });
+  }
+  for (const row of rows) {
+    if (!isNested(row)) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(row)) {
+      if (!isNested(value)) {
+        add(key, value);
+        continue;
+      }
+      for (const [nestedKey, nestedValue] of Object.entries(value)) {
+        if (!isNested(nestedValue)) {
+          add(`${key}.${nestedKey}`, nestedValue);
+        }
+      }
+    }
+  }
+  return columns;
+}
+function getColumnId(column) {
+  return column.id ?? column.field;
+}
+function resolveColumnLabel(column) {
+  const { header } = column;
+  if (header === void 0) {
+    return column.field.split(".").join(" ");
+  }
+  return typeof header === "function" ? header() : header;
+}
+function accessDotted(obj, path) {
+  return path.split(".").reduce((value, key) => isNested(value) ? value[key] : void 0, obj);
+}
+
+// src/util/sizing.ts
+var DEFAULT_COLUMN_SIZES = {
+  width: 150,
+  minWidth: 40,
+  maxWidth: Number.POSITIVE_INFINITY
+};
+var KEYBOARD_STEP = 10;
+function withDefaults(defaults) {
+  return { ...DEFAULT_COLUMN_SIZES, ...defaults };
+}
+function resolveColumnConstraints(column, defaults) {
+  const resolved = withDefaults(defaults);
+  return {
+    minWidth: column.minWidth ?? resolved.minWidth,
+    maxWidth: column.maxWidth ?? resolved.maxWidth
+  };
+}
+function clampColumnWidth(width, constraints) {
+  return Math.min(Math.max(width, constraints.minWidth), constraints.maxWidth);
+}
+function resolveColumnWidths(columns, sizing, options) {
+  const resolved = withDefaults(options?.sizes);
+  return columns.map((column) => {
+    const id = getColumnId(column);
+    const stored = sizing[id];
+    return {
+      column,
+      id,
+      sized: stored !== void 0,
+      width: clampColumnWidth(
+        stored ?? column.width ?? resolved.width,
+        resolveColumnConstraints(column, resolved)
+      ),
+      label: resolveColumnLabel(column),
+      resizable: column.resizable ?? options?.resizable ?? false,
+      alignment: column.alignment ?? alignmentForType(column.type ?? "string")
+    };
+  });
+}
+function totalColumnWidth(resolved) {
+  return resolved.reduce((total, entry) => total + entry.width, 0);
+}
+function beginColumnResize(column, startWidth, startPosition, defaults) {
+  return {
+    columnId: getColumnId(column),
+    startWidth,
+    startPosition,
+    constraints: resolveColumnConstraints(column, defaults)
+  };
+}
+function applyColumnResize(session, position) {
+  return clampColumnWidth(
+    session.startWidth + (position - session.startPosition),
+    session.constraints
+  );
+}
+function fitColumnsToWidth(resolved, availableWidth, defaults) {
+  const target = Math.floor(availableWidth);
+  if (resolved.length === 0 || totalColumnWidth(resolved) >= target) {
+    return resolved;
+  }
+  const entries = resolved.map((entry) => ({
+    entry,
+    width: entry.width,
+    maxWidth: resolveColumnConstraints(entry.column, defaults).maxWidth,
+    growable: !entry.sized
+  }));
+  const sum = () => entries.reduce((total, item) => total + item.width, 0);
+  for (; ; ) {
+    const growing = entries.filter(
+      (item) => item.growable && item.width < item.maxWidth
+    );
+    const surplus = target - sum();
+    if (surplus <= 0 || growing.length === 0) {
+      break;
+    }
+    const base = growing.reduce((total, item) => total + item.width, 0);
+    let clamped = false;
+    for (const item of growing) {
+      const share = base === 0 ? surplus / growing.length : surplus * item.width / base;
+      if (item.width + share >= item.maxWidth) {
+        item.width = item.maxWidth;
+        clamped = true;
+      } else {
+        item.width += share;
+      }
+    }
+    if (!clamped) {
+      break;
+    }
+  }
+  let remainder = target - entries.reduce((t, i) => t + Math.floor(i.width), 0);
+  return entries.map((item) => {
+    let width = Math.floor(item.width);
+    if (remainder > 0 && item.growable && width < item.maxWidth) {
+      width += 1;
+      remainder -= 1;
+    }
+    return { ...item.entry, width };
+  });
+}
+function sizeColumnToContent(measuredWidth, constraints, padding = 2) {
+  return clampColumnWidth(Math.ceil(measuredWidth + padding), constraints);
+}
+export {
+  DEFAULT_COLUMN_SIZES,
+  KEYBOARD_STEP,
+  accessDotted,
+  alignmentForType,
+  applyColumnResize,
+  beginColumnResize,
+  clampColumnWidth,
+  defineColumnsFromRows,
+  fitColumnsToWidth,
+  getColumnId,
+  resolveColumnConstraints,
+  resolveColumnLabel,
+  resolveColumnWidths,
+  sizeColumnToContent,
+  totalColumnWidth
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/util/grid.ts","../src/util/sizing.ts"],"sourcesContent":["import type { ColumnAlignment, ColumnDefinition, ColumnType } from \"../types\";\n\n/**\n * Narrows to a value worth drilling into. Mirrors the `LeafValue` union in\n * `../types`: arrays and `Date`s are cell values rather than groups of\n * columns, and `null` cannot be introspected. Keep the two in sync.\n */\nfunction isNested(value: unknown): value is Record<string, unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    !Array.isArray(value) &&\n    !(value instanceof Date)\n  );\n}\n\nfunction getType(value: unknown): ColumnType {\n  if (value instanceof Date) return \"dateTime\";\n  if (typeof value === \"string\") return \"string\";\n  if (typeof value === \"number\") return \"number\";\n  if (typeof value === \"boolean\") return \"boolean\";\n  if (typeof value === \"bigint\") return \"number\";\n  if (typeof value === \"symbol\") return \"string\";\n  return \"string\";\n}\n\n/**\n * How a column of `type` aligns by default. Numeric types align right so that\n * their digits line up by place value; everything else reads from the left.\n */\nexport function alignmentForType(type: ColumnType): ColumnAlignment {\n  switch (type) {\n    case \"number\":\n    case \"decimal\":\n    case \"currency\":\n    case \"percent\":\n      return \"right\";\n    default:\n      return \"left\";\n  }\n}\n\nfunction getAlignment(value: unknown): ColumnAlignment {\n  return alignmentForType(getType(value));\n}\n\n/**\n * Derives one column per field across `rows`, in the order each field is first\n * seen — so a key that only appears in a later row still gets a column,\n * appended at the end. Nested objects contribute their non-object properties\n * as `\"Parent.Child\"`; anything deeper is skipped, as is the nested object\n * itself.\n *\n * Order follows `Object.entries`, which lists integer-like keys first\n * regardless of the order they were written in.\n */\nexport function defineColumnsFromRows<Row>(\n  rows: readonly Row[],\n): readonly ColumnDefinition<Row>[] {\n  const columns: ColumnDefinition<Row>[] = [];\n  const seen = new Set<string>();\n\n  function add(field: string, value: unknown): void {\n    if (seen.has(field)) {\n      return;\n    }\n    seen.add(field);\n    columns.push({\n      field,\n      type: getType(value),\n      alignment: getAlignment(value),\n    });\n  }\n\n  for (const row of rows) {\n    if (!isNested(row)) {\n      continue;\n    }\n    for (const [key, value] of Object.entries(row)) {\n      if (!isNested(value)) {\n        add(key, value);\n        continue;\n      }\n      for (const [nestedKey, nestedValue] of Object.entries(value)) {\n        if (!isNested(nestedValue)) {\n          add(`${key}.${nestedKey}`, nestedValue);\n        }\n      }\n    }\n  }\n\n  return columns;\n}\n\n/**\n * The key state about a column is stored under, and the key it renders with.\n * Every such lookup goes through here so the two can never disagree.\n */\nexport function getColumnId<Row>(\n  column: ColumnDefinition<Row, unknown>,\n): string {\n  return column.id ?? column.field;\n}\n\n/**\n * What a column's header shows: its own `header`, called first if it is a\n * function, or else a label read off the field path — `\"Application.Id\"`\n * reading as `\"Application Id\"`.\n */\nexport function resolveColumnLabel<Row, Header>(\n  column: ColumnDefinition<Row, Header>,\n): Header | string {\n  const { header } = column;\n  if (header === undefined) {\n    return column.field.split(\".\").join(\" \");\n  }\n  // `Header` is open, so it could itself be a function type and the `typeof`\n  // check cannot narrow on its own. A header that is callable is the lazy\n  // form by definition — no adapter binds `Header` to a function.\n  return typeof header === \"function\" ? (header as () => Header)() : header;\n}\n\n/**\n * Accesses a value at a dotted path, e.g. `foo.bar.baz`.\n *\n * @param obj The object to access\n * @param path Path to the value, e.g. `\"foo.bar\"`\n * @returns The value at `path`, or `undefined` if it doesn't exist\n */\nexport function accessDotted(obj: unknown, path: string): unknown {\n  return path\n    .split(\".\")\n    .reduce((value, key) => (isNested(value) ? value[key] : undefined), obj);\n}\n","import type {\n  ColumnConstraints,\n  ColumnDefinition,\n  ColumnResizeSession,\n  ColumnResolveOptions,\n  ColumnSizeDefaults,\n  ColumnSizingState,\n  ResolvedColumn,\n} from \"../types\";\nimport { alignmentForType, getColumnId, resolveColumnLabel } from \"./grid\";\n\n/**\n * Applied to any column that does not size itself. The minimum is a width a\n * header stays legible at rather than a measured value — a column dragged\n * narrower than this reads as a rendering fault.\n */\nexport const DEFAULT_COLUMN_SIZES: ColumnSizeDefaults = {\n  width: 150,\n  minWidth: 40,\n  maxWidth: Number.POSITIVE_INFINITY,\n};\n\n/** How far one arrow key press moves a column edge. */\nexport const KEYBOARD_STEP = 10;\n\nfunction withDefaults(\n  defaults?: Partial<ColumnSizeDefaults>,\n): ColumnSizeDefaults {\n  return { ...DEFAULT_COLUMN_SIZES, ...defaults };\n}\n\n/**\n * The bounds `column` may be sized between. Resolved in one place so that a\n * drag, a clamp and an auto-fit cannot disagree about a column's limits.\n */\nexport function resolveColumnConstraints<Row>(\n  column: ColumnDefinition<Row, unknown>,\n  defaults?: Partial<ColumnSizeDefaults>,\n): ColumnConstraints {\n  const resolved = withDefaults(defaults);\n  return {\n    minWidth: column.minWidth ?? resolved.minWidth,\n    maxWidth: column.maxWidth ?? resolved.maxWidth,\n  };\n}\n\n/** Holds `width` within `constraints`. */\nexport function clampColumnWidth(\n  width: number,\n  constraints: ColumnConstraints,\n): number {\n  return Math.min(Math.max(width, constraints.minWidth), constraints.maxWidth);\n}\n\n/**\n * Pairs each column with everything needed to render it — the width it sits\n * at, the label its header shows, whether it may be resized and how its cells\n * align. Widths take the first of the sizing state, the column's own `width`,\n * and the default, then clamp.\n *\n * The sizing state winning means a user's drag outlives a re-render; a column\n * absent from it still tracks a `width` edited in the definition.\n */\nexport function resolveColumnWidths<Row, Header>(\n  columns: readonly ColumnDefinition<Row, Header>[],\n  sizing: ColumnSizingState,\n  options?: ColumnResolveOptions,\n): readonly ResolvedColumn<Row, Header>[] {\n  const resolved = withDefaults(options?.sizes);\n\n  return columns.map((column) => {\n    const id = getColumnId(column);\n    const stored = sizing[id];\n\n    return {\n      column,\n      id,\n      sized: stored !== undefined,\n      width: clampColumnWidth(\n        stored ?? column.width ?? resolved.width,\n        resolveColumnConstraints(column, resolved),\n      ),\n      label: resolveColumnLabel(column),\n      resizable: column.resizable ?? options?.resizable ?? false,\n      alignment: column.alignment ?? alignmentForType(column.type ?? \"string\"),\n    };\n  });\n}\n\nexport function totalColumnWidth<Row, Header>(\n  resolved: readonly ResolvedColumn<Row, Header>[],\n): number {\n  return resolved.reduce((total, entry) => total + entry.width, 0);\n}\n\n/**\n * Opens a resize. The session captures its constraints and starting point up\n * front, so applying a pointer position later is arithmetic on numbers alone —\n * which is what keeps the drag testable without a DOM.\n *\n * @param startPosition Where the pointer went down, on the axis being dragged.\n */\nexport function beginColumnResize<Row>(\n  column: ColumnDefinition<Row, unknown>,\n  startWidth: number,\n  startPosition: number,\n  defaults?: Partial<ColumnSizeDefaults>,\n): ColumnResizeSession {\n  return {\n    columnId: getColumnId(column),\n    startWidth,\n    startPosition,\n    constraints: resolveColumnConstraints(column, defaults),\n  };\n}\n\n/**\n * The width the dragged column takes with the pointer at `position`. The delta\n * is signed, so a right-to-left adapter negates it and nothing else changes.\n */\nexport function applyColumnResize(\n  session: ColumnResizeSession,\n  position: number,\n): number {\n  return clampColumnWidth(\n    session.startWidth + (position - session.startPosition),\n    session.constraints,\n  );\n}\n\n/**\n * Grows columns proportionally until they fill `availableWidth`.\n *\n * Growth only: columns that already meet or exceed the width are returned\n * untouched, so a container too narrow for them scrolls rather than crushing\n * them. Columns the user has sized are left at that width and the rest share\n * what is left, so dragging one column does not rubber-band it back.\n */\nexport function fitColumnsToWidth<Row, Header>(\n  resolved: readonly ResolvedColumn<Row, Header>[],\n  availableWidth: number,\n  defaults?: Partial<ColumnSizeDefaults>,\n): readonly ResolvedColumn<Row, Header>[] {\n  const target = Math.floor(availableWidth);\n  if (resolved.length === 0 || totalColumnWidth(resolved) >= target) {\n    return resolved;\n  }\n\n  const entries = resolved.map((entry) => ({\n    entry,\n    width: entry.width,\n    maxWidth: resolveColumnConstraints(entry.column, defaults).maxWidth,\n    growable: !entry.sized,\n  }));\n  const sum = () => entries.reduce((total, item) => total + item.width, 0);\n\n  // Clamping a column at its maximum frees surplus the others have to absorb,\n  // so a pass that clamped anything is followed by another.\n  for (;;) {\n    const growing = entries.filter(\n      (item) => item.growable && item.width < item.maxWidth,\n    );\n    const surplus = target - sum();\n    if (surplus <= 0 || growing.length === 0) {\n      break;\n    }\n\n    const base = growing.reduce((total, item) => total + item.width, 0);\n    let clamped = false;\n\n    for (const item of growing) {\n      const share =\n        base === 0 ? surplus / growing.length : (surplus * item.width) / base;\n\n      if (item.width + share >= item.maxWidth) {\n        item.width = item.maxWidth;\n        clamped = true;\n      } else {\n        item.width += share;\n      }\n    }\n\n    if (!clamped) {\n      break;\n    }\n  }\n\n  // Fractional widths would leave the table a sub-pixel short of its container\n  // and show a scrollbar that never goes away, so floor every column and hand\n  // the lost pixels back out one at a time.\n  let remainder = target - entries.reduce((t, i) => t + Math.floor(i.width), 0);\n\n  return entries.map((item) => {\n    let width = Math.floor(item.width);\n    if (remainder > 0 && item.growable && width < item.maxWidth) {\n      width += 1;\n      remainder -= 1;\n    }\n    return { ...item.entry, width };\n  });\n}\n\n/**\n * The width a column needs to show `measuredWidth` of content.\n *\n * `padding` is an allowance on top of the measurement, since a column sized to\n * exactly its content can still round down into an ellipsis.\n */\nexport function sizeColumnToContent(\n  measuredWidth: number,\n  constraints: ColumnConstraints,\n  padding = 2,\n): number {\n  return clampColumnWidth(Math.ceil(measuredWidth + padding), constraints);\n}\n"],"mappings":";AAOA,SAAS,SAAS,OAAkD;AAClE,SACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,KAAK,KACpB,EAAE,iBAAiB;AAEvB;AAEA,SAAS,QAAQ,OAA4B;AAC3C,MAAI,iBAAiB,KAAM,QAAO;AAClC,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,UAAW,QAAO;AACvC,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,SAAO;AACT;AAMO,SAAS,iBAAiB,MAAmC;AAClE,UAAQ,MAAM;AAAA,IACZ,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAEA,SAAS,aAAa,OAAiC;AACrD,SAAO,iBAAiB,QAAQ,KAAK,CAAC;AACxC;AAYO,SAAS,sBACd,MACkC;AAClC,QAAM,UAAmC,CAAC;AAC1C,QAAM,OAAO,oBAAI,IAAY;AAE7B,WAAS,IAAI,OAAe,OAAsB;AAChD,QAAI,KAAK,IAAI,KAAK,GAAG;AACnB;AAAA,IACF;AACA,SAAK,IAAI,KAAK;AACd,YAAQ,KAAK;AAAA,MACX;AAAA,MACA,MAAM,QAAQ,KAAK;AAAA,MACnB,WAAW,aAAa,KAAK;AAAA,IAC/B,CAAC;AAAA,EACH;AAEA,aAAW,OAAO,MAAM;AACtB,QAAI,CAAC,SAAS,GAAG,GAAG;AAClB;AAAA,IACF;AACA,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC9C,UAAI,CAAC,SAAS,KAAK,GAAG;AACpB,YAAI,KAAK,KAAK;AACd;AAAA,MACF;AACA,iBAAW,CAAC,WAAW,WAAW,KAAK,OAAO,QAAQ,KAAK,GAAG;AAC5D,YAAI,CAAC,SAAS,WAAW,GAAG;AAC1B,cAAI,GAAG,GAAG,IAAI,SAAS,IAAI,WAAW;AAAA,QACxC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAMO,SAAS,YACd,QACQ;AACR,SAAO,OAAO,MAAM,OAAO;AAC7B;AAOO,SAAS,mBACd,QACiB;AACjB,QAAM,EAAE,OAAO,IAAI;AACnB,MAAI,WAAW,QAAW;AACxB,WAAO,OAAO,MAAM,MAAM,GAAG,EAAE,KAAK,GAAG;AAAA,EACzC;AAIA,SAAO,OAAO,WAAW,aAAc,OAAwB,IAAI;AACrE;AASO,SAAS,aAAa,KAAc,MAAuB;AAChE,SAAO,KACJ,MAAM,GAAG,EACT,OAAO,CAAC,OAAO,QAAS,SAAS,KAAK,IAAI,MAAM,GAAG,IAAI,QAAY,GAAG;AAC3E;;;ACrHO,IAAM,uBAA2C;AAAA,EACtD,OAAO;AAAA,EACP,UAAU;AAAA,EACV,UAAU,OAAO;AACnB;AAGO,IAAM,gBAAgB;AAE7B,SAAS,aACP,UACoB;AACpB,SAAO,EAAE,GAAG,sBAAsB,GAAG,SAAS;AAChD;AAMO,SAAS,yBACd,QACA,UACmB;AACnB,QAAM,WAAW,aAAa,QAAQ;AACtC,SAAO;AAAA,IACL,UAAU,OAAO,YAAY,SAAS;AAAA,IACtC,UAAU,OAAO,YAAY,SAAS;AAAA,EACxC;AACF;AAGO,SAAS,iBACd,OACA,aACQ;AACR,SAAO,KAAK,IAAI,KAAK,IAAI,OAAO,YAAY,QAAQ,GAAG,YAAY,QAAQ;AAC7E;AAWO,SAAS,oBACd,SACA,QACA,SACwC;AACxC,QAAM,WAAW,aAAa,SAAS,KAAK;AAE5C,SAAO,QAAQ,IAAI,CAAC,WAAW;AAC7B,UAAM,KAAK,YAAY,MAAM;AAC7B,UAAM,SAAS,OAAO,EAAE;AAExB,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,OAAO,WAAW;AAAA,MAClB,OAAO;AAAA,QACL,UAAU,OAAO,SAAS,SAAS;AAAA,QACnC,yBAAyB,QAAQ,QAAQ;AAAA,MAC3C;AAAA,MACA,OAAO,mBAAmB,MAAM;AAAA,MAChC,WAAW,OAAO,aAAa,SAAS,aAAa;AAAA,MACrD,WAAW,OAAO,aAAa,iBAAiB,OAAO,QAAQ,QAAQ;AAAA,IACzE;AAAA,EACF,CAAC;AACH;AAEO,SAAS,iBACd,UACQ;AACR,SAAO,SAAS,OAAO,CAAC,OAAO,UAAU,QAAQ,MAAM,OAAO,CAAC;AACjE;AASO,SAAS,kBACd,QACA,YACA,eACA,UACqB;AACrB,SAAO;AAAA,IACL,UAAU,YAAY,MAAM;AAAA,IAC5B;AAAA,IACA;AAAA,IACA,aAAa,yBAAyB,QAAQ,QAAQ;AAAA,EACxD;AACF;AAMO,SAAS,kBACd,SACA,UACQ;AACR,SAAO;AAAA,IACL,QAAQ,cAAc,WAAW,QAAQ;AAAA,IACzC,QAAQ;AAAA,EACV;AACF;AAUO,SAAS,kBACd,UACA,gBACA,UACwC;AACxC,QAAM,SAAS,KAAK,MAAM,cAAc;AACxC,MAAI,SAAS,WAAW,KAAK,iBAAiB,QAAQ,KAAK,QAAQ;AACjE,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,SAAS,IAAI,CAAC,WAAW;AAAA,IACvC;AAAA,IACA,OAAO,MAAM;AAAA,IACb,UAAU,yBAAyB,MAAM,QAAQ,QAAQ,EAAE;AAAA,IAC3D,UAAU,CAAC,MAAM;AAAA,EACnB,EAAE;AACF,QAAM,MAAM,MAAM,QAAQ,OAAO,CAAC,OAAO,SAAS,QAAQ,KAAK,OAAO,CAAC;AAIvE,aAAS;AACP,UAAM,UAAU,QAAQ;AAAA,MACtB,CAAC,SAAS,KAAK,YAAY,KAAK,QAAQ,KAAK;AAAA,IAC/C;AACA,UAAM,UAAU,SAAS,IAAI;AAC7B,QAAI,WAAW,KAAK,QAAQ,WAAW,GAAG;AACxC;AAAA,IACF;AAEA,UAAM,OAAO,QAAQ,OAAO,CAAC,OAAO,SAAS,QAAQ,KAAK,OAAO,CAAC;AAClE,QAAI,UAAU;AAEd,eAAW,QAAQ,SAAS;AAC1B,YAAM,QACJ,SAAS,IAAI,UAAU,QAAQ,SAAU,UAAU,KAAK,QAAS;AAEnE,UAAI,KAAK,QAAQ,SAAS,KAAK,UAAU;AACvC,aAAK,QAAQ,KAAK;AAClB,kBAAU;AAAA,MACZ,OAAO;AACL,aAAK,SAAS;AAAA,MAChB;AAAA,IACF;AAEA,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAAA,EACF;AAKA,MAAI,YAAY,SAAS,QAAQ,OAAO,CAAC,GAAG,MAAM,IAAI,KAAK,MAAM,EAAE,KAAK,GAAG,CAAC;AAE5E,SAAO,QAAQ,IAAI,CAAC,SAAS;AAC3B,QAAI,QAAQ,KAAK,MAAM,KAAK,KAAK;AACjC,QAAI,YAAY,KAAK,KAAK,YAAY,QAAQ,KAAK,UAAU;AAC3D,eAAS;AACT,mBAAa;AAAA,IACf;AACA,WAAO,EAAE,GAAG,KAAK,OAAO,MAAM;AAAA,EAChC,CAAC;AACH;AAQO,SAAS,oBACd,eACA,aACA,UAAU,GACF;AACR,SAAO,iBAAiB,KAAK,KAAK,gBAAgB,OAAO,GAAG,WAAW;AACzE;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@gridkitjs/core",
+  "version": "0.0.1",
+  "description": "Framework-agnostic data-grid logic: column resolution, alignment and sizing.",
+  "license": "MIT",
+  "author": "Blagoja Blazhevski",
+  "homepage": "https://github.com/blagojablazhevski/gridkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blagojablazhevski/gridkit.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "datagrid",
+    "grid",
+    "table",
+    "headless",
+    "typescript",
+    "framework-agnostic"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}