@k4a_l/dirtreeist 0.3.3 → 1.0.0

package/README.md

@@ -4,15 +4,8 @@ Create a directory Structure Diagram from a markdown lists.
 
 ## Installation
 
-#### yarn
-
 ```shell
 yarn add @k4a_l/dirtreeist
-```
-
-### npm
-
-```shell
 npm install @k4a_l/dirtreeist
 ```
 
@@ -147,6 +140,38 @@ sometext
 　　　　　　└─ 4
 ```
 
+### Memo and note
+
+Set `delimiter` and the text after it becomes a **memo**, lined up in a column.
+
+An item with **no name, only a memo** is not a directory. It is a **note** belonging to its parent, so longer remarks can be written as an outline without adding fake entries to the tree. Children of a note are notes too, even if they have a name.
+
+#### Input
+
+```markdown
+- /components -- UI
+  - -- has buttons and modals
+    - -- Storybook ready
+  - App.tsx -- entry point
+  - App.css -- style
+- tsconfig.json -- settings
+- README.md -- docs
+- /utils
+```
+
+#### Output (`{ delimiter: '--' }`)
+
+```text
+├─/components    UI
+│　│             ・has buttons and modals
+│　│             　・Storybook ready
+│　├─App.tsx    entry point
+│　└─App.css    style
+├─tsconfig.json  settings
+├─README.md      docs
+└─/utils
+```
+
 ## How to use
 
 ### TypeScript
@@ -168,8 +193,6 @@ import dirtreeist, { Options } from '@k4a_l/dirtreeist'
 
 const options: Options = {}
 const outputs = dirtreeist(markdown, options) // DirTree[] => output[]
-
-console.log(outputs)
 ```
 
 or
@@ -181,35 +204,42 @@ const dirTrees = parse(markdown) // markdown => DirTree[]
 
 const options: Options = {}
 const outputs = dirTrees.map((dirTree) => convert(dirTree, options)) // DirTree[] => output[]
-
-console.log(outputs)
 ```
 
-### Type
+### Custom rendering
 
-#### Structure
+To style parts of the output yourself, use `layout` instead of `convert`. It returns the same result as flat, already-aligned line data — `'node'`, `'note'` or `'empty'`, each split into branch / name / padding / memo, plus the source `DirNode`.
 
-```ts
-type DirNode = {
-  name: string
-  children: DirNode[]
-}
-
-type DirTree = DirNode[]
+```tsx
+import { layout } from '@k4a_l/dirtreeist'
+
+layout(dirTree, options).map((line, i) =>
+  line.type === 'node' ? (
+    <div key={i}>
+      <span className="branch">{line.branch}</span>
+      <span onClick={() => select(line.node)}>{line.name}</span>
+      {line.gap}
+      <span className="memo">{line.memo}</span>
+    </div>
+  ) : (
+    ...
+  )
+)
 ```
 
-#### Options
+Padding comes as ready-made strings rather than widths, so you never count characters yourself. Joining every field of a line gives back exactly what `convert` outputs:
 
 ```ts
-type Options = {
-  treeType?: 'normal' | 'bold' | 'ascii'
-  emptyBeforeUpperHierarche?: boolean
-  spaceBeforeName?: boolean
-  spaceSize?: number
-}
+convert(dirTree, options) === layout(dirTree, options).map(lineToString).join('\n')
 ```
 
-### Description of options
+That padding only holds in monospace. If names and memos get different fonts or sizes, ignore `gap` and lay the fields out with CSS instead.
+
+### Type
+
+See [src/types/index.ts](src/types/index.ts)
+
+### Options
 
 #### treeType
 
@@ -220,7 +250,6 @@ default:`normal`
 ```
 │
 ├─
-│
 └─
 ```
 
@@ -229,7 +258,6 @@ default:`normal`
 ```
 ┃
 ┣━
-┃
 ┗━
 ```
 
@@ -237,8 +265,6 @@ default:`normal`
 
 ```
 |
-+
-|
 +-
 ```
 
@@ -252,11 +278,9 @@ default:`false`
 (true)
 ├─/components
 │　├─App.tsx
-│　└─App.css
 │
 ├─config.json
 └─/utils
-　　└─converter.ts
 　　└─parser.ts
 ```
 
@@ -269,10 +293,8 @@ default: `false`
 ```text
 ├─ /components
 │　├─ App.tsx
-│　└─ App.css
 ├─ config.json
 └─ /utils
-　　└─ converter.ts
 　　└─ parser.ts
 ```
 
@@ -285,9 +307,101 @@ default:`2`
 ```text
 ├──/components
 │　　├──App.tsx
-│　　└──App.css
 ├──config.json
 └──/utils
-　　　└──converter.ts
 　　　└──parser.ts
 ```
+
+#### keepMarkdown : boolean
+
+default:`false`
+
+Whether to keep markdown notation in lists.
+
+##### true
+
+```text
+Input:
+- **bold**
+- [google](https://google.com)
+
+Output:
+├─**bold**
+└─[google](https://google.com)
+```
+
+#### delimiter : string | false
+
+default: `false`
+
+Separates a name from its memo; `false` disables memos.
+
+Splits at the first occurrence; later ones stay in the memo. Occurrences inside link URLs, code spans and escapes (`\`) are skipped, so names can contain the delimiter.
+
+#### memoAlign : 'all' | 'siblings' | 'none'
+
+default: `all`
+
+```text
+all                             siblings
+├─/components    UI             ├─/components  UI
+│　├─A.tsx      entry          │　├─A.tsx  entry
+│　└─A.css      style          │　└─A.css  style
+├─tsconfig.json  settings       ├─tsconfig.json  settings
+├─README.md      docs           ├─README.md      docs
+└─/utils                        └─/utils
+```
+
+#### memoGap : number
+
+default: `2`
+
+Minimum number of half-width spaces between a name and its memo.
+
+#### memoMaxColumn : number | false
+
+default: `false`
+
+Lines wider than this stop deciding the memo column, so one long name cannot drag every memo right. A ceiling on who *decides* the column, not a width it is padded out to.
+
+```text
+false                                20
+├─a                        short   ├─a  short
+├─b                        short   ├─b  short
+├─/very/deeply/nested/dir  long    ├─/very/deeply/nested/dir  long
+└─c                        short   └─c  short
+```
+
+#### noteAlignToMemo : boolean
+
+default: `true`
+
+Whether notes line up with the memo column. `false` puts them right after the branch, which holds up better with deep trees or long notes.
+
+```text
+true                              false
+├─/components  UI                 ├─/components  UI
+│　│           ・has buttons      │　│　・has buttons
+│　│           　・Storybook      │　│　　・Storybook
+│　└─Button.tsx  generic          │　└─Button.tsx  generic
+```
+
+#### noteBullet : string
+
+default: `・`
+
+The mark in front of each note line. An empty string removes it.
+
+#### noteIndentSize : number
+
+default: `2`
+
+Indent width of one note level, in half-width spaces.
+
+#### cjkFont : boolean
+
+default: `true`
+
+Box drawing characters are full-width in CJK fonts, half-width elsewhere. Set `false` for the latter.
+
+> Alignment assumes monospace, and counts `keepMarkdown` names by their rendered length (`**bold**` is 4).

package/dist/index.d.ts

@@ -1,9 +1,129 @@
-import { parse } from './modules/parse.js';
-import { convert } from './modules/convert.js';
-import { DirTree, Options } from './types/index';
-import { symbolSets } from './constants/constant.js';
+//#region src/types/index.d.ts
+/**
+ * 名前を持たずメモだけの行(`- -- xxx`)。
+ * 名前の右に書くmemoと区別してnoteと呼ぶ。アウトライン形式で階層を持てる。
+ */
+type NoteNode = {
+  text: string;
+  children: NoteNode[];
+};
+type DirNode = {
+  name: string;
+  /** 名前と同じ行に書かれたメモ */
+  memo?: string;
+  /** 子として書かれた、名前を持たないメモ */
+  notes?: NoteNode[];
+  children: DirNode[];
+};
+type DirTree = DirNode[];
+type ParseOptions = {
+  keepMarkdown: boolean;
+  /** 名前とmemo/noteを割る文字。memoとnoteの両方に効くので接頭辞を付けない */
+  delimiter: string | false;
+};
+type ConvertOptions = {
+  treeType: (typeof treeTypeValues)[number];
+  emptyBeforeUpperHierarchy: boolean;
+  spaceBeforeName: boolean;
+  spaceSize: number;
+  /**
+   * CJKフォントで表示する前提かどうか。
+   * 罫線や丸数字は環境によって半角・全角どちらにも描画されるため、
+   * メモを揃える幅の計算をどちらに寄せるかの判断に使う。
+   */
+  cjkFont: boolean;
+  keepMarkdown: boolean;
+  /** memo(行内)をどの範囲で揃えるか */
+  memoAlign: (typeof memoAlignValues)[number];
+  /** 名前とmemoの間の最小間隔(半角スペース換算) */
+  memoGap: number;
+  /**
+   * memo列の上限桁数。falseなら無制限。
+   * 極端に長い名前1つに全行が引きずられるのを防ぐためのもので、
+   * 上限を超える名前の行だけがmemoGapぶんだけ空けて置かれ、揃いから外れる。
+   */
+  memoMaxColumn: number | false;
+  /** noteをmemo列に揃えるか。falseなら罫線の直後に置く */
+  noteAlignToMemo: boolean;
+  /** noteの行頭に付ける記号。空文字なら付けない */
+  noteBullet: string;
+  /** noteの階層1つあたりのインデント幅(半角スペース換算) */
+  noteIndentSize: number;
+};
+/**
+ * 出力1行分。階層構造を上から下へのフラットな行列に落としたもの。
+ * 空白は揃え済みの文字列で持つので、連結すればそのまま出力になる。
+ * 利用側で独自にレンダリングするときは、この単位でスタイルを当てられる。
+ */
+type NodeLine = {
+  type: "node";
+  /** 罫線部分。`│　├─` など */
+  branch: string;
+  name: string;
+  /** 名前とメモの間の空白。メモがなければ空文字 */
+  gap: string;
+  /** 名前と同じ行に書かれたメモ */
+  memo?: string;
+  /** この行のもとになったDirNode */
+  node: DirNode;
+  /** 階層の深さ。0が最上位 */
+  hierarchy: number;
+};
+type NoteLine = {
+  type: "note";
+  /** 罫線部分。親の位置を引き継いだもの */
+  branch: string;
+  /** 罫線からnote本文までの空白 */
+  gap: string;
+  /** note内階層のインデント */
+  indent: string;
+  /** 行頭の記号 */
+  bullet: string;
+  text: string;
+  /** note内の階層。0が最上位 */
+  depth: number;
+  /** このnoteが属するDirNode */
+  node: DirNode;
+  /** この行のもとになったNoteNode */
+  noteNode: NoteNode;
+};
+/** 罫線だけの空行(emptyBeforeUpperHierarchy)。 */
+type EmptyLine = {
+  type: "empty";
+  branch: string;
+};
+type Line = NodeLine | NoteLine | EmptyLine;
+type OptionsBase = ParseOptions & ConvertOptions;
+type SymbolSet = {
+  vertical: string;
+  horizontal: string;
+  crossing: string;
+  end: string;
+  space: string;
+};
+type Options = Partial<OptionsBase>;
+//#endregion
+//#region src/constants/constant.d.ts
+declare const symbolSets: { [key in OptionsBase["treeType"]]: SymbolSet };
+declare const defaultOptions: OptionsBase;
+declare const treeTypeValues: readonly ["normal", "bold", "ascii"];
+declare const memoAlignValues: readonly ["all", "siblings", "none"];
+//#endregion
+//#region src/modules/convert.d.ts
+/** Lineを1行の文字列にする。 */
+declare const lineToString: (line: Line) => string;
+/**
+ * 階層構造を、上から下へのフラットな行データに落とす。
+ * 罫線・名前・空白・メモが分かれているので、利用側で独自にレンダリングできる。
+ */
+declare const layout: (dirTree: DirTree, options?: Options) => Line[];
+declare const convert: (dirTree: DirTree, options?: Options) => string;
+//#endregion
+//#region src/modules/parse.d.ts
+declare const parse: (chunk: string, options?: Options) => DirTree[];
+//#endregion
+//#region src/index.d.ts
 declare const dirtreeist: (markdown: string, option?: Options) => string[];
-export { parse, convert, symbolSets };
-export default dirtreeist;
-export type { DirTree, Options };
+//#endregion
+export { type DirNode, type DirTree, type EmptyLine, type Line, type NodeLine, type NoteLine, type NoteNode, type Options, convert, dirtreeist as default, defaultOptions, layout, lineToString, memoAlignValues, parse, symbolSets, treeTypeValues };
 //# sourceMappingURL=index.d.ts.map