@qoretechnologies/reqraft 0.10.9 → 0.10.11

package/.claude/CLAUDE.md

@@ -1,4 +1,36 @@
-# ReQraft AI Coding Agent Instructions
+@~/Projects/instruction-files/CLAUDE.md
+@~/Projects/instruction-files/stacks/frontend/FRONTEND.md
+
+# ReQraft (toolkit-react) — Claude entry point
+
+## Shared Qore rules (READ FIRST)
+
+The two `@`-imports above load the shared rules from the **instruction-files**
+repo: the org-wide baseline (`CLAUDE.md`) and the frontend ruleset
+(`stacks/frontend/FRONTEND.md`) — git safety, commit conventions, CI
+monitoring, `/audit`, the Reqore-first rule, the Storybook + Qlip visual-change
+flow, story descriptions, and more. Those files point on to
+`stacks/frontend/BRAND_DESIGN.md` for brand / UI-design decisions (read it
+before building any visual surface). **Everything below this section is
+specific to ReQraft (toolkit-react).**
+
+**If the imports above did not load** — you don't see the shared rules because
+this repo is cloned somewhere other than `~/Projects/instruction-files` — find
+the shared repo before doing any frontend work:
+
+1. Check for a gitignored **`.instruction-files-path`** file at this repo's
+   root. If it exists, read the path `P` from it, then read `P/CLAUDE.md` and
+   `P/stacks/frontend/FRONTEND.md` (+ `P/stacks/frontend/BRAND_DESIGN.md` for
+   UI work) and follow them.
+2. Otherwise locate the `instruction-files` repo on disk (try
+   `~/Projects/instruction-files`, then your other project roots). If found at
+   `P`, write `P` into `.instruction-files-path` (create it — it's gitignored)
+   so future sessions skip the search, then read the files above.
+3. If it isn't cloned anywhere, **STOP and ask the user to clone it**:
+   `git clone git@github.com:qoretechnologies/instruction-files.git ~/Projects/instruction-files`
+   Do not proceed with frontend work until the shared rules are loaded.
+
+# ReQraft (toolkit-react) — project-specific rules
 
 ## Project Overview
 
@@ -18,16 +50,6 @@ ReQraft (`@qoretechnologies/reqraft`) is a **React hooks and components toolkit*
 
 ## Architecture Essentials
 
-### General Development Practices
-
-- Focus on user experience and performance first; complexity and tech debt are secondary
-- Follow existing code patterns; refer to similar hooks/components for guidance
-- Check if a helper or utility already exists before writing a new one
-- Use TypeScript with strict typing; prefix interfaces with `I` and types with `T`
-- Always use named exports for React components and hooks
-- Use functional components with React hooks; wrap in `memo()` unless there's a reason not to
-- Wrap callbacks in `useCallback()` and computed values in `useMemo()` unless there's a reason not to
-
 ### Provider Stack (`src/providers/`)
 
 The app must be wrapped in `ReqraftProvider` (or initialized via `initializeReqraft()`):
@@ -145,10 +167,13 @@ yarn build:test         # Type-check without emit
 - `pre-push` hook enforces: `build:test:prod`, `lint`, `test`
 - Branch naming: always start with the issue number, e.g. `feature/49_pooled-connections`
 
-### Versioning
+### Versioning — every PR to `develop` MUST bump the version
+
+`.github/workflows/beta_release.yml` runs on **every push to `develop`** and publishes to NPM using whatever `version` is in `package.json` at push time. A merge without a bump therefore tries to re-publish an already-published version and **fails** (NPM refuses to re-publish). This applies to **every** PR — features, fixes, chores, and docs-only changes alike. There is no exception.
 
-- The package is in **beta** (pre-1.0): bump the **patch** for a PR — e.g. `0.10.4` → `0.10.5`. Do NOT bump minor/major for ordinary feature/fix PRs while in beta.
-- Bump in `package.json` only (no git tag): `npm version patch --no-git-tag-version`, and include it in the PR's commit.
+- Bump the **patch** for an ordinary PR while in beta (pre-1.0) — e.g. `0.10.9` → `0.10.10`. Do NOT bump minor/major for ordinary feature/fix PRs.
+- Bump in `package.json` only (no git tag): `npm version patch --no-git-tag-version`, and include the bump in the PR's commit.
+- If another PR bumps to the same version before yours merges, rebase and bump again — the version at merge time must be strictly greater than the last published one.
 
 ### Testing Patterns
 
@@ -167,8 +192,6 @@ yarn build:test         # Type-check without emit
 
 ### Naming
 
-- Interfaces: `I` prefix (e.g., `IReqraftUseFetch`)
-- Types: `T` prefix (e.g., `TReqraftMenu`)
 - Enums: PascalCase (e.g., `ReqraftWebSocketStatus`)
 - Hooks: `useReqraft*` prefix
 - Providers: `Reqraft*Provider`
@@ -249,7 +272,5 @@ yarn build:test         # Type-check without emit
 
 ## Other
 
-- You may need to source zsh to get some commands (like `gh`) working: `source ~/.zshrc`
-- Branch naming convention: `feature/<issue-number>_<short-description>` (e.g., `feature/49_pooled-connections`)
 - This library is a **peer-dependency consumer** of ReQore — do not copy ReQore internals here; import from `@qoretechnologies/reqore` instead
 - `yarn update-reqore` updates ReQore to the latest beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoretechnologies/reqraft",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "ReQraft is a collection of React components and hooks that are used across Qore Technologies' products made using the ReQore component library from Qore.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/components/dpqlEditor/DpqlEditor.stories.tsx

@@ -511,7 +511,15 @@ const meta = {
 export default meta;
 export type Story = StoryObj<typeof meta>;
 
-export const Empty: Story = {};
+export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the DpqlEditor with no value — the editor mounts empty and ready for input.',
+      },
+    },
+  },
+};
 
 /**
  * No chips / templates — just a valid DPQL literal expression so we can
@@ -524,18 +532,42 @@ export const WithPlainText: Story = {
   args: {
     value: '1 == 1 && "hello" != "world"',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the DpqlEditor with a plain DPQL literal expression — no field references or templates, so the editor mounts as plain text with no tag chips.',
+      },
+    },
+  },
 };
 
 export const WithFieldReference: Story = {
   args: {
     value: '@name == "Alice"',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the DpqlEditor with an @name field reference — the editor mounts with a tag chip for the field and the literal string operand.',
+      },
+    },
+  },
 };
 
 export const WithTemplateVariable: Story = {
   args: {
     value: 'contains("$local:input", "es")',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the DpqlEditor with a contains() call whose first argument is a $local:input template — the template renders as a tag chip inside the call.',
+      },
+    },
+  },
 };
 
 export const WithMixedContent: Story = {
@@ -544,6 +576,14 @@ export const WithMixedContent: Story = {
     // qore-2/design/dpql-syntax.md §"Logical Operators".
     value: '@name == $data:{1.name} && @age > $config:min_age',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the DpqlEditor with mixed content — two @field references, two $data / $config templates and the DPQL "&&" logical operator between them, each rendered as its own chip or token.',
+      },
+    },
+  },
 };
 
 /**
@@ -1014,6 +1054,14 @@ export const ReadOnly: Story = {
     value: '@name == "Alice"',
     readOnly: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the DpqlEditor with a valued expression but readOnly enabled — the field chip and literal render but the editor cannot be edited.',
+      },
+    },
+  },
 };
 
 /**
@@ -1131,6 +1179,14 @@ export const CanTypeText: Story = {
     value: '',
     onChange: fn(),
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the empty DpqlEditor and types "hello" into it — the editor accepts the plain text and fires onChange.',
+      },
+    },
+  },
   play: async ({ canvasElement, args }) => {
     const canvas = within(canvasElement);
 
@@ -1153,6 +1209,14 @@ export const LspCompletionRoundtrip: Story = {
     value: '',
     onChange: fn(),
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the empty DpqlEditor and types the "@" trigger — the LSP receives a textDocument/completion request against a dpql:// document URI and the dropdown mounts with the canned @name / @status / @age items.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
 
@@ -1199,7 +1263,15 @@ export const LspCompletionRoundtrip: Story = {
  * single physical connection and a single `initialize` handshake.
  */
 export const TwoEditorsOneConnection: Story = {
-  parameters: { chromatic: { disable: true } },
+  parameters: {
+    chromatic: { disable: true },
+    docs: {
+      description: {
+        story:
+          'Renders two DpqlEditor instances side by side — both share a single WebSocket via LspSharedConnection and each opens its own document URI, so the server sees one initialize but two didOpen notifications.',
+      },
+    },
+  },
   render: () => (
     <>
       <DpqlEditorWithState value='name' />