qstd 0.3.58 → 0.3.59

package/ATOMIC_MODULES.md

@@ -451,6 +451,43 @@ type DurationMs = number;
 type TokenId = string;
 ```
 
+### Module-aware type naming
+
+**Since we use namespace imports, avoid redundant prefixes.** The module name already provides context:
+
+```typescript
+// ❌ AVOID: Redundant module prefix in type name
+// contracts/media/types.ts
+export interface Media { ... }      // Used as Media.Media
+export type MediaType = "song" | "video";  // Used as Media.MediaType
+
+// ✅ PREFER: Short names, let module provide context
+// contracts/media/types.ts
+export interface t { ... }          // Used as Media.t
+export type Type = "song" | "video"; // Used as Media.Type
+export interface Version { ... }     // Used as Media.Version
+```
+
+**The `t` convention:** For the "main" type of a module (the one it's named after), use lowercase `t`. This pattern comes from ML/OCaml and reads naturally with namespace imports:
+
+```typescript
+// Usage is clean and non-redundant
+const song: Media.t = { ... };
+const item: Queue.t = { ... };
+
+// Compare to awkward repetition
+const song: Media.Media = { ... };  // ❌
+const item: Queue.QueueItem = { ... };  // ❌
+```
+
+**Guidelines:**
+- `Module.t` — The main/primary type (the entity the module represents)
+- `Module.Type` — A discriminated union of subtypes (e.g., `"song" | "video"`)
+- `Module.Config`, `Module.Options` — Configuration/options for the module
+- `Module.Event`, `Module.Version` — Related concepts without redundant prefix
+
+**When to keep prefixes:** If a type is re-exported and used without the module namespace, a prefix may still be appropriate to avoid ambiguity at the consumption site.
+
 ### Document type fields with JSDoc
 
 **Add JSDoc to fields when the name is generic but the value has specific meaning.** Especially `id` fields with particular formats, foreign key references, or `string`/`number` fields with constraints.
@@ -899,30 +936,52 @@ import type { ContentBlock } from "contracts/entry";
 
 ### Import path setup
 
-Configure path aliases in each package's tsconfig.json:
+**Option 1: Workspace dependency (recommended)**
+
+Add contracts as a workspace dependency in each consuming package:
 
 ```json
-// packages/server/tsconfig.json
+// packages/client/package.json
 {
-  "compilerOptions": {
-    "paths": {
-      "contracts/*": ["../contracts/src/*"],
-      "entities/*": ["src/entities/*"]
-    }
+  "dependencies": {
+    "contracts": "workspace:*"
+  }
+}
+```
+
+Configure the contracts package exports to expose submodules:
+
+```json
+// packages/contracts/package.json
+{
+  "name": "contracts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*/index.ts"
   }
 }
+```
+
+This uses standard package resolution. No tsconfig paths needed for contracts.
+
+**Option 2: Path aliases**
+
+If you prefer path aliases, configure them in tsconfig.json:
 
-// packages/client/tsconfig.json
+```json
+// packages/server/tsconfig.json
 {
   "compilerOptions": {
     "paths": {
-      "contracts/*": ["../contracts/src/*"],
-      "entities/*": ["./src/entities/*"]
+      "contracts/*": ["../contracts/src/*/index.ts", "../contracts/src/*"],
+      "entities/*": ["src/entities/*"]
     }
   }
 }
 ```
 
+Note: The path pattern needs both `*/index.ts` fallback for directories and `*` for direct files.
+
 ### When to create a contract
 
 1. **Same type in both environments** - If you're copying a type from server to client (or vice versa), it belongs in contracts.

package/dist/block/drawer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drawer.d.ts","sourceRoot":"","sources":["../../src/block/drawer.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAmX9B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,2CAMxD;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,2CAYrD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,uDAkDrD"}
+{"version":3,"file":"drawer.d.ts","sourceRoot":"","sources":["../../src/block/drawer.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAsZ9B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,2CAMxD;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,2CAYrD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,uDAkDrD"}

package/dist/react/index.cjs

@@ -2622,6 +2622,34 @@ var accordion_default = Accordion;
 var MotionDiv4 = motionTags.div;
 var MotionBtn2 = motionTags.button;
 var breakpoint = ["(min-width: 600px)"];
+function requirePortalRootForDrawer() {
+  if (typeof document === "undefined") {
+    throw new Error(
+      [
+        `[qstd] Block is="drawer" requires a DOM (document is undefined).`,
+        `If you're server-rendering, render drawers only on the client.`
+      ].join("\n")
+    );
+  }
+  const portal = document.getElementById("portal");
+  if (!portal) {
+    throw new Error(
+      [
+        `[qstd] You cannot use <Block is="drawer" /> unless your HTML contains a portal root: <div id="portal"></div>.`,
+        ``,
+        `No element with id="portal" was found in the document.`,
+        ``,
+        `Fix: add this next to your app root in your HTML (usually right under #root):`,
+        ``,
+        `  <div id="root"></div>`,
+        `  <div id="portal"></div>`,
+        ``,
+        `Without #portal, qstd cannot render drawers (they use React portals).`
+      ].join("\n")
+    );
+  }
+  return portal;
+}
 function DrawerComponent(props) {
   const ref = React3__namespace.default.useRef(null);
   const dragHandleRef = React3__namespace.default.useRef(null);
@@ -2717,6 +2745,7 @@ function DrawerComponent(props) {
     closeFnRef.current?.();
   };
   if (!mounted) return null;
+  const portalRoot = requirePortalRootForDrawer();
   return reactDom.createPortal(
     /* @__PURE__ */ jsxRuntime.jsx(
       framerMotion.AnimatePresence,
@@ -2863,7 +2892,7 @@ function DrawerComponent(props) {
         )
       }
     ),
-    document.getElementById("portal")
+    portalRoot
   );
 }
 var DrawerContext = React3__namespace.default.createContext({

package/dist/react/index.js

@@ -2599,6 +2599,34 @@ var accordion_default = Accordion;
 var MotionDiv4 = motionTags.div;
 var MotionBtn2 = motionTags.button;
 var breakpoint = ["(min-width: 600px)"];
+function requirePortalRootForDrawer() {
+  if (typeof document === "undefined") {
+    throw new Error(
+      [
+        `[qstd] Block is="drawer" requires a DOM (document is undefined).`,
+        `If you're server-rendering, render drawers only on the client.`
+      ].join("\n")
+    );
+  }
+  const portal = document.getElementById("portal");
+  if (!portal) {
+    throw new Error(
+      [
+        `[qstd] You cannot use <Block is="drawer" /> unless your HTML contains a portal root: <div id="portal"></div>.`,
+        ``,
+        `No element with id="portal" was found in the document.`,
+        ``,
+        `Fix: add this next to your app root in your HTML (usually right under #root):`,
+        ``,
+        `  <div id="root"></div>`,
+        `  <div id="portal"></div>`,
+        ``,
+        `Without #portal, qstd cannot render drawers (they use React portals).`
+      ].join("\n")
+    );
+  }
+  return portal;
+}
 function DrawerComponent(props) {
   const ref = React3__default.useRef(null);
   const dragHandleRef = React3__default.useRef(null);
@@ -2694,6 +2722,7 @@ function DrawerComponent(props) {
     closeFnRef.current?.();
   };
   if (!mounted) return null;
+  const portalRoot = requirePortalRootForDrawer();
   return createPortal(
     /* @__PURE__ */ jsx(
       AnimatePresence,
@@ -2840,7 +2869,7 @@ function DrawerComponent(props) {
         )
       }
     ),
-    document.getElementById("portal")
+    portalRoot
   );
 }
 var DrawerContext = React3__default.createContext({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qstd",
-  "version": "0.3.58",
+  "version": "0.3.59",
   "description": "Standard Block component and utilities library with Panda CSS",
   "author": "malin1",
   "license": "MIT",