sellmate-design-system-react 9.0.0-beta.8 → 9.0.0-beta.80

package/dist/lib/row-metrics.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 가변 행 높이 가상 스크롤의 계산부 — DOM 을 모르는 순수 자료구조다.
+ * `SSelect`(드롭다운 목록)와 `STable`(본문 행)이 함께 쓴다.
+ *
+ * 아직 그려지지 않은 행은 추정치로 두고, 화면에 나온 행은 실측으로 덮는다. 그래서
+ * "모든 행이 같은 높이"라는 가정 없이도 스크롤 위치 ↔ 행 인덱스를 오갈 수 있다 —
+ * depth 그룹 헤더처럼 리프와 높이가 다른 행이 섞여도 어긋나지 않는다.
+ * (Quasar QVirtualScroll 의 `virtual-scroll-item-size` 가 "추정치일 뿐"인 것과 같은 모델)
+ *
+ * 수천 행에서 렌더마다 새 배열을 만들면 그 자체가 비용이라, 제자리에서 고친다.
+ * 소유자는 ref 하나로 들고 있고, 화면에 반영할 필요가 있을 때만 리렌더를 건다.
+ */
+export interface RowMetrics {
+    /** 행별 높이. 실측 전에는 `estimate` 가 들어 있다 */
+    sizes: number[];
+    /** 실측을 마친 행인지 — 추정치를 평균에 섞지 않으려고 구분한다 */
+    measured: boolean[];
+    /** `offsets[i]` = 0..i-1 행 높이의 합. 길이는 `sizes.length + 1` 이라 마지막이 전체 높이다 */
+    offsets: number[];
+    /** 아직 안 그려진 행에 쓸 높이. 실측이 쌓일수록 그 평균으로 수렴한다 */
+    estimate: number;
+    /** 추정치 갱신용 누적 — 평균을 매번 다시 훑지 않으려고 합과 개수를 들고 있는다 */
+    measuredCount: number;
+    measuredTotal: number;
+    /** 이 인덱스부터 `offsets` 가 낡았다. `Infinity` 면 최신 */
+    dirtyFrom: number;
+}
+export declare function createRowMetrics(count: number, estimate: number): RowMetrics;
+/**
+ * 목록 길이가 바뀌었을 때 표를 맞춘다.
+ *
+ * 늘어난 만큼은 추정치로 채우고 **앞쪽 실측은 그대로 둔다** — 무한 로딩은 뒤에 이어붙이는
+ * 것이라, 여기서 표를 새로 만들면 이미 잰 높이를 버리고 스크롤이 튄다. 줄어들 때는 잘라낸다
+ * (검색으로 목록이 좁아지는 경우인데, 그때는 같은 인덱스가 다른 행이므로 실측도 함께 버린다).
+ */
+export declare function resizeRowMetrics(metrics: RowMetrics, count: number): void;
+/** 목록이 통째로 다른 것으로 갈렸을 때 — 실측을 전부 버리고 추정치만 남긴다 */
+export declare function resetRowMetrics(metrics: RowMetrics, count: number): void;
+/**
+ * 실측 높이를 반영한다. 값이 실제로 달라졌으면 `true`.
+ *
+ * 추정치도 실측 평균으로 함께 끌어당긴다 — 한 번도 안 그려진 뒤쪽 수천 행의 높이가
+ * 그만큼 사실에 가까워져, 스크롤바 길이와 "끝까지 내렸을 때"의 위치가 맞는다.
+ * 다만 1px 미만의 흔들림으로 표 전체를 다시 세우지는 않는다.
+ */
+export declare function setRowSize(metrics: RowMetrics, index: number, size: number): boolean;
+/**
+ * 낡은 구간의 누적 오프셋을 다시 센다. 이미 최신이면 아무 일도 하지 않는다.
+ * 바뀐 지점 앞은 그대로 두고 거기서부터만 이어 세므로, 아래쪽 행을 재도 전체를 훑지 않는다.
+ */
+export declare function rebuildOffsets(metrics: RowMetrics): void;
+/** 목록 전체 높이 */
+export declare function totalSize(metrics: RowMetrics): number;
+/** `index` 번 행의 위쪽 끝 y */
+export declare function offsetOf(metrics: RowMetrics, index: number): number;
+export declare function sizeOf(metrics: RowMetrics, index: number): number;
+/**
+ * y 좌표에 놓인 행의 인덱스 (이진 탐색). 목록 끝을 넘으면 마지막 행을 준다.
+ * 수천 행에서 스크롤마다 훑으면 그게 곧 렉이라 선형 탐색을 쓰지 않는다.
+ */
+export declare function indexAtOffset(metrics: RowMetrics, y: number): number;

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>;