sellmate-design-system-react 9.0.0-beta.4 → 9.0.0-beta.41

package/dist/lib/doc-sections.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Storybook 의 Guide 문서 페이지가 쓰는 마크다운 슬라이서.
+ *
+ * Guide 페이지는 **자기 원문을 갖지 않는다.** AGENTS.md·README.md 를 `?raw` 로 읽어
+ * 필요한 `## ` 섹션만 잘라 {@link https://storybook.js.org/docs/writing-docs/doc-blocks Markdown 블록}에 넘긴다.
+ * 문서를 Storybook 에 복사해 두면 AGENTS.md 가 바뀔 때마다 조용히 낡고,
+ * 이 저장소는 이미 한 변경이 네 곳(README·stories·playground·AGENTS.md)에 흩어져 있다 —
+ * 다섯 번째 사본을 만들지 않는 것이 이 파일의 존재 이유다.
+ *
+ * @example
+ * import agents from '../../AGENTS.md?raw';
+ * <Markdown>{mdSections(agents, '2.')}</Markdown>
+ */
+/**
+ * `## ` 섹션을 제목 접두어로 잘라 이어 붙인다. 접두어는 번호(`'2.'`)든 제목(`'설치'`)이든 된다.
+ *
+ * 넘긴 순서가 아니라 **원문 순서**로 이어 붙인다 — 문서 안의 "위에서 말한" 류의 참조가
+ * 순서를 뒤집으면 거짓이 되기 때문이다.
+ *
+ * 찾지 못한 접두어가 하나라도 있으면 던진다. 조용히 빈 페이지가 되면
+ * AGENTS.md 의 절 번호가 바뀐 것을 아무도 모른 채 배포된다.
+ */
+export declare function mdSections(md: string, ...prefixes: string[]): string;
+/**
+ * 원문의 저장소 상대 링크(`./README.md`)를 Storybook 문서 경로로 바꾼다.
+ *
+ * 원문은 npm 패키지에 그대로 실려 소비 앱의 `node_modules` 에서 읽히는 것이 1차 용도라
+ * 링크가 파일 경로다. Storybook 안에서는 그 경로가 404 이므로 여기서만 갈아 끼운다 —
+ * 원문은 손대지 않는다.
+ *
+ * 표에 없는 링크는 그대로 둔다.
+ */
+export declare function relinkToDocs(md: string): string;
+/** {@link mdSections} + {@link relinkToDocs} — Guide 페이지가 쓰는 기본 조합 */
+export declare function guideSections(md: string, ...prefixes: string[]): string;

package/dist/lib/field-width.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 필드 폭 등급 — 폼 컨트롤의 너비를 정하는 공용 어휘.
+ *
+ * 폭은 `maxLength`(= 스키마 상한)로 정한다. 상한이 등급 안에 들어오면 그 등급을 주고,
+ * 상한이 `xl` 을 넘거나 상한 자체가 없으면 행 전체(`"100%"`)로 둔다.
+ * 이 판단은 `sellmate/field-width-grade` 린트 규칙이 자동으로 검사한다 — 규칙과 이 타입은
+ * 같은 토큰(`--cmp-field-width-*`)을 근거로 삼는다.
+ *
+ * px 를 직접 적는 것보다 등급을 쓰는 편이 낫다. 토큰 값이 바뀌면 등급은 따라가지만
+ * 화면에 박아 둔 px 는 그 자리에 남는다.
+ */
+/** 폭 등급 이름. 값은 `--cmp-field-width-<grade>` 토큰이 갖는다. */
+export declare const FIELD_WIDTH_GRADES: readonly ["xs", "sm", "md", "lg", "xl"];
+export type SFieldWidthGrade = (typeof FIELD_WIDTH_GRADES)[number];
+/**
+ * 폭 prop 이 받는 값.
+ *
+ * `(string & {})` 는 유니온 리터럴 자동완성을 유지하기 위한 관용 표현이다 — 이게 없으면
+ * `string` 이 등급 리터럴을 흡수해 편집기가 등급을 제안하지 못한다. (`SColor` 와 같은 방식)
+ */
+export type SFieldWidth = SFieldWidthGrade | number | (string & {});
+export declare const isFieldWidthGrade: (v: unknown) => v is SFieldWidthGrade;
+/**
+ * 폭 값을 CSS 길이로 바꾼다.
+ *   등급   → `var(--cmp-field-width-<grade>)`
+ *   숫자   → px
+ *   그 외  → 그대로 (`"100%"` · `"20rem"`)
+ *
+ * 빈 값(`undefined` · `''` · `0`)은 "지정하지 않음" 으로 본다.
+ */
+export declare const fieldWidthValue: (v?: SFieldWidth) => string | undefined;

package/dist/lib/floating-height.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Radix Floating Content 를 창 높이 안에 가두기 위한 헬퍼 — floating-width.ts 의 높이 버전.
+ *
+ * Radix 는 충돌이 나면 위치만 밀 뿐(shift) 높이는 줄이지 않는다 — 콘텐츠가 창보다 높으면
+ * 밀려난 자리에서 그대로 화면 밖으로 삐져나간다. 실제로 줄이려면 size 미들웨어가 계산해
+ * 두는 available-height 를 상한으로 직접 걸어야 한다.
+ */
+/** Radix Popover 계열(SPortal·SSelect·SChipInput·SPopover·STooltip 등)이 노출하는 가용 높이. */
+export declare const POPOVER_AVAILABLE_HEIGHT = "var(--radix-popover-content-available-height)";
+/** Radix DropdownMenu 계열(SDropdownButton)이 노출하는 가용 높이. */
+export declare const DROPDOWN_AVAILABLE_HEIGHT = "var(--radix-dropdown-menu-content-available-height)";
+/**
+ * 높이 제약을 가용 높이 안으로 가둔다. 값이 없으면 가용 높이 자체가 상한이 된다.
+ */
+export declare function clampToAvailableHeight(value: string | number | undefined, availableHeight: string): string;

package/dist/lib/story-docs.d.ts

@@ -2,9 +2,10 @@
  * 자동 생성 README(`README.md?raw`)에서 **Methods (ref)** 섹션만 뽑아
  * Storybook Docs 의 컴포넌트 설명으로 주입한다.
  *
- * Props/Events/default/설명은 이제 Controls(react-docgen-typescript)가 완전히 보여주므로
- * README 표는 중복이다. deps/mermaid 그래프는 소비자용 문서에 불필요.
- * ref 핸들 메서드(focus/open 등)만 Controls 로 표현되지 않으므로 이것만 남긴다.
+ * Props/Events/default/설명은 Controls(react-docgen-typescript)가 완전히 보여주므로
+ * README 표는 중복이고, prop 이 쓰는 타입 선언은 {@link readmeTypeDetails} 가
+ * Controls 의 Description 칸에 직접 붙여준다. deps/mermaid 그래프는 소비자용 문서에 불필요.
+ * ref 핸들 메서드(focus/open 등)만 어느 쪽으로도 표현되지 않으므로 이것만 남긴다.
  *
  * 메서드가 없으면 `undefined` 를 반환한다 — description 을 빈 문자열로 덮어쓰지 않고
  * docgen 이 추출한 컴포넌트 요약(prose)이 그대로 노출되도록 하기 위함.
@@ -14,3 +15,18 @@
  * const meta = { parameters: { docs: { description: { component: readmeDocs(readme) } } } };
  */
 export declare function readmeDocs(md: string): string | undefined;
+/** README 상단의 컴포넌트 섹션(`### SXxx`) 이름들. `## Types` 이후의 `###` 는 타입이라 제외된다 */
+export declare function readmeComponentNames(md: string): string[];
+/**
+ * Controls 표의 Description 칸에는 prop 설명 아래 타입 요약이 붙는데,
+ * `SChipFilterField[] | SChipFilterGroup[]` 처럼 **이름만** 찍혀 그것만 보고는 값을 채울 수 없다.
+ * Storybook 은 `table.type.detail` 이 있으면 그 요약을 클릭해 펼칠 수 있게 해주므로,
+ * 자동 생성 README 의 Types 섹션에서 해당 선언을 찾아 채워 넣는다.
+ *
+ * 반환값은 `prop 이름 → 선언 원문`. 타입이 다시 참조하는 타입까지 전부 따라간다 —
+ * 여기가 Storybook 에서 타입을 볼 수 있는 유일한 자리라 `SChipFilterField.options?:
+ * SChipFilterOption[]` 의 `SChipFilterOption` 이 빠지면 결국 소스를 열어야 한다.
+ * 다만 팝오버가 감당할 만한 길이를 유지해야 하므로, 직접 참조한 타입만 JSDoc 을 살리고
+ * 거기서 파생된 것들은 형태만 남긴다.
+ */
+export declare function readmeTypeDetails(md: string, component: string): Record<string, string>;

package/dist/lib/truncated-value-tooltip.d.ts

@@ -0,0 +1,18 @@
+import { type Ref, type ReactNode } from 'react';
+/** 여러 ref 에 같은 노드를 흘려보낸다 — 소비자용 ref 와 측정용 ref 가 같은 `<input>` 을 가리켜야 한다 */
+export declare function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): (node: T | null) => void;
+export interface TruncatedValueTooltip {
+    /** 측정 대상 `<input>` 에 붙일 ref. 소비자 ref 와는 `mergeRefs` 로 합친다 */
+    valueRef: Ref<HTMLInputElement>;
+    /** 측정 대상에 붙일 호버 핸들러 */
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    /** 필드 어디든 함께 렌더한다 (Portal 이라 레이아웃을 차지하지 않는다) */
+    tooltip: ReactNode;
+}
+export declare function useTruncatedValueTooltip({ enabled, text, }: {
+    /** `readOnly` 이고 비활성이 아닐 때만 켠다 */
+    enabled: boolean;
+    /** 툴팁에 표시할 전문. 화면에 보이는 문자열이어야 한다(숫자 필드의 천단위 콤마 포함) */
+    text: string;
+}): TruncatedValueTooltip;