@forgebook/story-format 0.2.0 → 0.2.1

package/dist/src/csf.d.ts

@@ -123,6 +123,12 @@ export type ArgType = {
 export type ArgTypes<TArgs> = {
     readonly [Name in keyof TArgs]?: ArgType;
 } & Readonly<Record<string, ArgType>>;
+/**
+ * Where a component's required props are listed in its API reference and Props tab: `in-groups` puts them first
+ * inside each group (and in the props that name none), `section` lists them all in one "Required" section before
+ * every group, each naming its group, and `false` keeps the order of the source.
+ */
+export type RequiredFirst = "in-groups" | "section" | false;
 /** A component's or a story's design, in the tool it was drawn in. */
 export type StoryDesign = {
     /**
@@ -209,6 +215,13 @@ export type StoryParameters = {
      * first appear. Written plainly, a list of string literals (the index reads it).
      */
     readonly propGroups?: readonly string[];
+    /**
+     * Where the required props are listed (`RequiredFirst`): on a meta, for the component's page and every story's
+     * Props tab; on a story, for its own Props tab, over the meta's. Both win over the catalogue's `requiredFirst`;
+     * a reader's "Required first" switch turns the ordering on or off over all three, never choosing the layout.
+     * `in-groups` by default. Written plainly, `"in-groups"`, `"section"` or `false` (the index reads it).
+     */
+    readonly requiredFirst?: RequiredFirst;
     /** CSF's documentation block; the catalogue reads the component's one-line description from it. */
     readonly docs?: {
         readonly description?: {

package/dist/src/source.d.ts

@@ -12,7 +12,7 @@
  *
  * @module
  */
-import type { StoryDeviceSetting, StoryGroup } from "./csf.ts";
+import type { RequiredFirst, StoryDeviceSetting, StoryGroup } from "./csf.ts";
 import type { StoryTextTable } from "./texts.ts";
 /** What a Figma file is, as the embed's address names it. */
 export type FigmaFileKind = "design" | "proto" | "board" | "slides" | "deck";
@@ -70,6 +70,8 @@ export type StoryIndexEntry = {
     readonly isLogic?: boolean;
     /** The story's own `parameters.device`, when it sets one: the device it is shown in by default. */
     readonly device?: StoryDeviceSetting;
+    /** The story's own `parameters.requiredFirst`, when it sets one: where its Props tab lists the required props. */
+    readonly requiredFirst?: RequiredFirst;
     /**
      * The first sentence of the story's TSDoc, or its `parameters.docs.description.story`: what it shows and what to
      * notice.
@@ -107,6 +109,11 @@ export type StoryFileIndex = {
     readonly isLogic?: boolean;
     /** The meta's `parameters.device`, when it sets one: every story's device unless it sets its own fields. */
     readonly device?: StoryDeviceSetting;
+    /**
+     * The meta's `parameters.requiredFirst`, when it sets one: where the component's page and its stories' Props tabs
+     * list the required props, unless a story says otherwise.
+     */
+    readonly requiredFirst?: RequiredFirst;
     /** The meta's `alsoIn`, when it sets one: the other places the component is listed in. */
     readonly alsoIn?: readonly string[];
     /** The meta's `related`, when it sets one: the titles of the components its page names at its top. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgebook/story-format",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The story format of Forgebook: the CSF 3 types a story file is written with, generic over a framework, the StorySource a package hands a catalogue, the texts inside the stories in the shown language, and the story clock a Live story reads. No dependency: a library's stories depend on their framework's package, never on the catalogue that shows them.",
   "keywords": [
     "stories",