@colixsystems/widget-sdk 0.98.0 → 0.99.0

package/dist/index.d.ts

@@ -385,6 +385,27 @@ export interface DatastoreClient {
     get(tableIdOrName: string): Promise<unknown>;
   };
   schema(tableId: string): Promise<unknown>;
+  /**
+   * sc-5206 — REQ-ACL-COMPOSER-GATING: the caller's effective table-level
+   * (+ optional per-record) permissions. Backs `useCanWrite`.
+   */
+  myPermissions(
+    tableId: string,
+    options?: { recordId?: string },
+  ): Promise<{
+    can_read_schema: boolean;
+    can_create: boolean;
+    can_read_records: boolean;
+    can_read: boolean;
+    can_write: boolean;
+    can_delete: boolean;
+    record?: {
+      can_read: boolean;
+      can_write: boolean;
+      can_delete: boolean;
+      can_grant: boolean;
+    };
+  }>;
   records(tableId: string): {
     list(query?: Query): Promise<ListEnvelope>;
     get(recordId: string): Promise<unknown>;
@@ -971,6 +992,52 @@ export function useDatastoreSchema(
   tableId: string | null | undefined,
 ): SchemaResult;
 
+/** sc-5206 — one prop key `useBoundColumns` resolves to a schema column. */
+export interface BoundColumnSpec {
+  dataType?: string | string[];
+  /** When true, an unresolved key is omitted from `missing`. */
+  optional?: boolean;
+}
+
+export type BoundColumnShape = Record<string, BoundColumnSpec>;
+
+export interface BoundColumnsResult {
+  /** Resolved column NAME per key — drop-in for `record[props.titleField]`. */
+  columns: Record<string, string | undefined>;
+  /** The full Column object per key, as `useDatastoreSchema` returns it. */
+  resolved: Record<string, DatastoreSchemaColumn | undefined>;
+  /** Keys whose spec is not `optional: true` and did not resolve. */
+  missing: string[];
+  loading: boolean;
+  error: DatastoreError | null;
+}
+
+/**
+ * sc-5206 — resolve author-bound column NAMES from a widget's own props,
+ * built on `useDatastoreSchema`. Falls back name -> case-insensitive name ->
+ * first unclaimed column matching `dataType`, so a column an author renamed
+ * after install still resolves. Never throws for a missing column — an
+ * unresolved key reads `undefined` and, when not `optional: true`, is named
+ * in `missing`. Falsy `tableId` collapses to `{ columns: {}, resolved: {},
+ * missing: Object.keys(shape), loading: false, error: null }`.
+ */
+export function useBoundColumns<TProps = Record<string, unknown>>(
+  tableId: string | null | undefined,
+  shape: BoundColumnShape,
+  props: TProps,
+): BoundColumnsResult;
+
+/**
+ * sc-5206 — keep whatever `buildQuery()` returns at a STABLE reference across
+ * renders when its (JSON-serialised) content hasn't changed, so it can be
+ * passed straight into `useDatastoreQuery`'s second argument instead of a
+ * hand-rolled `useMemo` with an easy-to-get-wrong deps array. Pure React
+ * state — no host / WidgetContext required. Never throws: a `buildQuery`
+ * that throws degrades to a stable `undefined`; a result that can't be
+ * diffed (e.g. circular) degrades to "always a new reference".
+ */
+export function useStableQuery<T = unknown>(buildQuery: () => T): T | undefined;
+
 /** sc-4932 — one field a draft may target, with a dropdown's closed option set. */
 export interface InterpretDraftField {
   column: string;
@@ -1852,6 +1919,34 @@ export function useRecordPermissions(
   recordId: string | null | undefined,
 ): RecordPermissionsResult;
 
+export interface CanWriteOptions {
+  recordId?: string;
+}
+
+export interface CanWriteResult {
+  canWrite: boolean;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+}
+
+/**
+ * sc-5206 — is the signed-in caller permitted to write to `tableId` (or, with
+ * `options.recordId`, to that one row)? A FLOOR, not a full replacement for
+ * domain-specific write rules: a widget whose rule is more specific than the
+ * table ACL (e.g. "only the assigned user may edit this row") must still
+ * hand-check that in addition to this hook. Answers "signed in AND
+ * permitted" — pair with `useUser()` to also tell "not signed in" apart from
+ * "signed in but forbidden". Falsy `tableId`, or a host that has not
+ * injected `ctx.datastore.myPermissions`, collapses to `{ canWrite: false,
+ * loading: false, error: null, refetch: async () => undefined }` rather than
+ * throwing.
+ */
+export function useCanWrite(
+  tableId: string | null | undefined,
+  options?: CanWriteOptions,
+): CanWriteResult;
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;

package/dist/index.js

@@ -15,6 +15,9 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useBoundColumns,
+  useStableQuery,
+  useCanWrite,
   useInterpretDraft,
   useAsset,
   useAssetsByTag,

package/dist/index.native.js

@@ -15,6 +15,9 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useBoundColumns,
+  useStableQuery,
+  useCanWrite,
   useInterpretDraft,
   useAsset,
   useAssetsByTag,

package/dist/linter.cjs

@@ -944,6 +944,71 @@ function _datastoreErrorHandlingRules(source) {
   ];
 }
 
+// sc-5206 — soft warning: a `useDatastoreQuery` argument built from a raw
+// `const q = useMemo(() => ({...}), [...])` re-fetches in a loop the moment
+// the deps array is wrong (sc-1579's volatile-query gate exists because of
+// exactly this mistake). Flags only when the file has NOT already reached
+// for `useStableQuery`, the hook that removes the deps array entirely.
+function _rawUseMemoIntoDatastoreQueryRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseStableQuery\s*\(/.test(code)) return [];
+  const callRe = /\buseDatastoreQuery\s*\(\s*[^,()]+,\s*([A-Za-z_$][\w$]*)\s*[,)]/g;
+  const findings = [];
+  const sourceLines = source.split(/\r?\n/);
+  const seen = new Set();
+  let m;
+  while ((m = callRe.exec(code))) {
+    const varName = m[1];
+    if (seen.has(varName)) continue;
+    const memoRe = new RegExp(`\\bconst\\s+${varName}\\s*=\\s*useMemo\\s*\\(`);
+    const memoMatch = memoRe.exec(code);
+    if (!memoMatch || memoMatch.index >= m.index) continue;
+    seen.add(varName);
+    const line = code.slice(0, memoMatch.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "raw-useMemo-into-datastore-query",
+      severity: "warning",
+      label:
+        `Pass useStableQuery(() => ({...})) as the query argument instead ` +
+        `of hand-rolling useMemo — it removes the wrong-deps-array failure ` +
+        `mode.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// sc-5206 — soft warning, the write-gate twin of `write-not-gated-on-user`.
+// A widget that hand-derives write permission from `useUser().groupIds` /
+// `.roles` re-implements the table ACL client-side and drifts from it the
+// moment the ACL changes; `useCanWrite(tableId)` reads the same rule the
+// write endpoint enforces. Flags only when the file has NOT already reached
+// for it.
+function _handRolledWriteGateRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseCanWrite\s*\(/.test(code)) return [];
+  const userCall = /\buseUser\s*\(\s*\)/.exec(code);
+  if (!userCall) return [];
+  if (!/\.(groupIds|roles)\b/.test(code)) return [];
+  const hasWrite =
+    /\.(create|update)\s*\(/.test(code) ||
+    /\buseDatastoreMutation\s*\(/.test(code);
+  if (!hasWrite) return [];
+  const line = code.slice(0, userCall.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "hand-rolled-write-gate",
+      severity: "warning",
+      label:
+        `Gate this write on useCanWrite(tableId) as the permission FLOOR — ` +
+        `IN ADDITION TO (never instead of) a narrower roles/groupIds rule.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   const code = _stripNonCode(source, { keepStrings: true });
@@ -1113,6 +1178,9 @@ function lintSource(source, options) {
   findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
   findings.push(..._datastoreErrorHandlingRules(source));
+  // sc-5206 — soft warnings steering a widget toward the two new hooks.
+  findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
+  findings.push(..._handRolledWriteGateRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -1077,6 +1077,71 @@ function _datastoreErrorHandlingRules(source) {
   ];
 }
 
+// sc-5206 — soft warning: a `useDatastoreQuery` argument built from a raw
+// `const q = useMemo(() => ({...}), [...])` re-fetches in a loop the moment
+// the deps array is wrong (sc-1579's volatile-query gate exists because of
+// exactly this mistake). Flags only when the file has NOT already reached
+// for `useStableQuery`, the hook that removes the deps array entirely.
+function _rawUseMemoIntoDatastoreQueryRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseStableQuery\s*\(/.test(code)) return [];
+  const callRe = /\buseDatastoreQuery\s*\(\s*[^,()]+,\s*([A-Za-z_$][\w$]*)\s*[,)]/g;
+  const findings = [];
+  const sourceLines = source.split(/\r?\n/);
+  const seen = new Set();
+  let m;
+  while ((m = callRe.exec(code))) {
+    const varName = m[1];
+    if (seen.has(varName)) continue;
+    const memoRe = new RegExp(`\\bconst\\s+${varName}\\s*=\\s*useMemo\\s*\\(`);
+    const memoMatch = memoRe.exec(code);
+    if (!memoMatch || memoMatch.index >= m.index) continue;
+    seen.add(varName);
+    const line = code.slice(0, memoMatch.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "raw-useMemo-into-datastore-query",
+      severity: "warning",
+      label:
+        `Pass useStableQuery(() => ({...})) as the query argument instead ` +
+        `of hand-rolling useMemo — it removes the wrong-deps-array failure ` +
+        `mode.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// sc-5206 — soft warning, the write-gate twin of `write-not-gated-on-user`.
+// A widget that hand-derives write permission from `useUser().groupIds` /
+// `.roles` re-implements the table ACL client-side and drifts from it the
+// moment the ACL changes; `useCanWrite(tableId)` reads the same rule the
+// write endpoint enforces. Flags only when the file has NOT already reached
+// for it.
+function _handRolledWriteGateRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseCanWrite\s*\(/.test(code)) return [];
+  const userCall = /\buseUser\s*\(\s*\)/.exec(code);
+  if (!userCall) return [];
+  if (!/\.(groupIds|roles)\b/.test(code)) return [];
+  const hasWrite =
+    /\.(create|update)\s*\(/.test(code) ||
+    /\buseDatastoreMutation\s*\(/.test(code);
+  if (!hasWrite) return [];
+  const line = code.slice(0, userCall.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "hand-rolled-write-gate",
+      severity: "warning",
+      label:
+        `Gate this write on useCanWrite(tableId) as the permission FLOOR — ` +
+        `IN ADDITION TO (never instead of) a narrower roles/groupIds rule.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   // Comments are blanked (string contents kept) so a commented-out example —
@@ -1276,6 +1341,9 @@ export function lintSource(source, options) {
   findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
   findings.push(..._datastoreErrorHandlingRules(source));
+  // sc-5206 — soft warnings steering a widget toward the two new hooks.
+  findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
+  findings.push(..._handRolledWriteGateRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js"
   },
   "engines": {
     "node": ">=18"