@shiodome47/planner 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,8 +5,9 @@
5
5
  | 入り口 | 中身 | 状態 |
6
6
  |---|---|---|
7
7
  | `@shiodome47/planner/core` | **土台**。データの形と決まりごと(画面なし。計算だけ) | ✅ 使えます |
8
- | `@shiodome47/planner/timeline` | 時間軸の画面 | これから |
9
- | `@shiodome47/planner/projects` | プロジェクトの画面(並べ替えは [linkshelf](https://www.npmjs.com/package/linkshelf) の `<CardBoard>`) | これから |
8
+ | `@shiodome47/planner/timeline` | **時間軸の画面** `<Timeline>`(React) | ✅ 使えます |
9
+ | `@shiodome47/planner/projects` | **プロジェクトの画面** `<Projects>`(React。並べ替えは [linkshelf](https://www.npmjs.com/package/linkshelf) の `<CardBoard>`) | ✅ 使えます |
10
+ | `@shiodome47/planner/style.css` | 画面の見た目(`.planner` の中だけに効く) | ✅ |
10
11
 
11
12
  時間軸とプロジェクトは、同じ「やること」の一覧を見ています。期日を入れたやることは、プロジェクトのカードにも、時間軸の列にも出ます。つなぐのは画面ではなく、この土台(`core`)です。
12
13
 
@@ -14,6 +15,70 @@
14
15
  npm install @shiodome47/planner
15
16
  ```
16
17
 
18
+ ## 画面(timeline・projects)
19
+
20
+ データ(`PlannerData`)と「今」を渡し、変更を `onChange` で受け取って保存するだけで、時間軸とプロジェクトの画面になります。2 つの画面は同じデータを見るので、プロジェクトに期日つきの目標を足すと、時間軸の列にも出ます。
21
+
22
+ ```tsx
23
+ import { Timeline } from '@shiodome47/planner/timeline'
24
+ import { Projects } from '@shiodome47/planner/projects'
25
+ import { applyChanges, type Changes, type PlannerData } from '@shiodome47/planner/core'
26
+ import '@shiodome47/planner/style.css'
27
+
28
+ function App() {
29
+ const [data, setData] = useState<PlannerData>(load())
30
+ const onChange = useCallback((c: Changes) => {
31
+ setData((d) => applyChanges(d, c))
32
+ save(c) // 保存先は自由(IndexedDB・サーバー・同期)
33
+ }, [])
34
+ const now = useNow() // 1 分ごとなどに新しくする
35
+
36
+ return tab === 'timeline' ? <Timeline data={data} now={now} onChange={onChange} /> : <Projects data={data} now={now} onChange={onChange} />
37
+ }
38
+ ```
39
+
40
+ | 設定 | 中身 |
41
+ |---|---|
42
+ | `data` / `now` / `onChange` | データ・今・変更を受け取る関数(必須) |
43
+ | `simple` | すっきり表示(慣れたら要らない説明の文字を消す) |
44
+ | `theme` | `light` / `dark` / `system`(既定。端末の設定に合わせる) |
45
+ | `className` | 外枠に足すクラス |
46
+
47
+ - 画面の中で使う React の部品・ドラッグ(@dnd-kit)・アイコン(lucide-react)・linkshelf は、`npm install` で一緒に入ります。React(18・19)は使う側のもの
48
+ - 列を広げた状態や、書きかけの文字は、見る人のブラウザに覚えます(名前は `planner:…`)
49
+ - 時間軸は、スマホの幅では列を横にすべらせ、上の帯から列を選べます。プロジェクトは、画面の幅に合わせて段組みになり、カードをドラッグで並べ替えられます(キーボードでも)
50
+
51
+ ### 習慣を終える(卒業・お休み)・完全に消す
52
+
53
+ 習慣(ルーチン目標)の … から選びます。
54
+
55
+ | 操作 | どうなるか |
56
+ |---|---|
57
+ | **卒業・お休みにする…** | 「卒業(身についた)」か「お休み(続かなかった・今はやめる)」を選び、ひとこと(理由など。なくてもよい)を添える。チェックの一覧からは外れ、習慣の一番下の **「これまでの習慣(n)」**(はじめは閉じている)に残る。チェックの記録は消えない。下ろした先の、まだ終えていないやることは消える |
58
+ | これまでの習慣の … →「また始める」 | チェックの一覧の一番下へ戻す。終えた日と別の日なら、休んでいた間を覚えておき、振り返りの数に入れない |
59
+ | これまでの習慣の … →「卒業・お休みを変える…」 | 終え方とひとことを直す(終えた日はそのまま) |
60
+ | **完全に消す** | 記録ごと消す(元に戻せない)。チェックの記録があるときは、確かめてから消す |
61
+
62
+ 「これまでの習慣」の 1 行には、卒業(🎓)かお休み(🌙)の印・名前・期間(9/1〜11/22)・できた割合(毎日なら「できた日 82%」。毎週なら週で数える)・ひとことが出ます。時間軸では各列の習慣の一番下、プロジェクトではルーチン目標の一番下(「これまでのルーチン目標」)です。
63
+
64
+ ### 色を合わせる
65
+
66
+ 見た目は `.planner` の中だけに効き、色は変数で決まります。使う側の CSS で上書きすると、アプリの色に合わせられます。
67
+
68
+ ```css
69
+ .planner {
70
+ --pl-accent: #2563eb; /* 決定のボタン・今日の列・ドラッグの線 */
71
+ --pl-panel: #fff; /* 列・カード */
72
+ --pl-panel-2: #f3f4f6; /* 入力欄・行にマウスを乗せたとき */
73
+ --pl-border: #e5e7eb;
74
+ --pl-text: #111827;
75
+ --pl-muted: #6b7280;
76
+ --pl-sticky-top: 56px; /* 上に固定の見出しがあるページでは、その高さ */
77
+ }
78
+ ```
79
+
80
+ ほかに `--pl-page-bg`・`--pl-accent-text`・`--pl-danger`・`--pl-warning`・`--pl-ok` があります。プロジェクトの色は `PROJECT_COLORS`(`teal`・`blue` など 8 色)。
81
+
17
82
  ## 土台(core)
18
83
 
19
84
  ### データの形
@@ -27,7 +92,7 @@ const data: PlannerData = { tasks: [], habits: [], projects: [] }
27
92
  | 形 | 中身 |
28
93
  |---|---|
29
94
  | `Task` | やること。`horizon`(列)・`priority`(A〜D・P)・`due`(期日 YYYY-MM-DD)・`projectId` など |
30
- | `Habit` | 習慣(くり返し)。`period`(毎日・毎週・毎月・毎年)と「その日」(`weekday`・`day`・`yearDay`) |
95
+ | `Habit` | 習慣(くり返し)。`period`(毎日・毎週・毎月・毎年)と「その日」(`weekday`・`day`・`yearDay`)。終えたら `endedAt`・`endedAs`(`'graduated'` 卒業/`'paused'` お休み)・`endNote`(ひとこと)。また始めたら、休んでいた間を `breaks` に残す |
31
96
  | `Project` | プロジェクト・テーマ。テーマの中にプロジェクトを入れられる(1 段だけ) |
32
97
 
33
98
  アプリは、`PlannerData` に自分の項目(日記など)を足した形で持って構いません。土台の関数は、足した項目を変えずに残します。
@@ -65,9 +130,10 @@ data = applyChanges(data, toggleDone(data, data.tasks[0], now))
65
130
  | 時間軸 | `buildColumns(data, now)` 列ごとの表示(やること・習慣・明日の欄・来週の欄)/`horizonForDue(due, now)` 期日から列/`effectiveHorizon(task, now)` |
66
131
  | やること | `newTask` `toggleDone` `placeDown`(今日やる、などで下ろす)`returnUp` `moveTo` `moveStep` `setPriority` `setDue` `removeTask` `reorderTasks` `postponeToTomorrow` `bringToToday` |
67
132
  | 習慣 | `newHabit` `toggleHabit` `toggleHabitAll` `placeHabitDown` `habitToTask` `reorderHabits` |
133
+ | 習慣を終える | `endHabit(data, habit, 'graduated' \| 'paused', ひとこと, now)` 卒業・お休み(終えた習慣なら、終え方とひとことだけ変える)/`resumeHabit(data, habit, now)` また始める/`endedHabits(habits)` 終えた習慣を新しい順に。`buildColumns` の列は、終えた習慣を `habits` に入れず `ended` に入れる |
68
134
  | くり返しの「その日」 | 毎月: `withDay(habit, 20 \| 'end' \| 'w2-3' \| 'wL-5')`/毎週・毎年: `withWhen(habit, 3 \| '12-06' \| '12')`/`whenLabel` `whenDate` `monthDayDate` |
69
135
  | プロジェクト | `newProject` `topProjects` `childProjects` `moveProject` `removeProject` `reorderProjects` `projectGoals` `reorderGoals` |
70
- | 振り返り | `doneOn(data, day, now)` その日に済ませたこと/`streak(habit, now)` 続いた日数/`toggleHabitOnDay` `finishOnDay`(過ぎた日に付け直す) |
136
+ | 振り返り | `doneOn(data, day, now)` その日に済ませたこと/`streak(habit, now)` 続いた日数/`toggleHabitOnDay` `finishOnDay`(過ぎた日に付け直す)/`habitActiveOn(habit, day)` その日に続けていたか(始める前・終えたあと・休んでいた間は数えない。「毎日 3/4」の分母に使う)/`habitRecord(habit, now)` 始めてから終えるまでの、できた数と期間の数 |
71
137
  | 日付 | `dayKey` `weekKey` `weekStart` `addDays` `periodLabel` `dueLabel` `shortDueLabel` |
72
138
  | 当てる | `applyChanges(data, changes)` / `mergeById(list, puts, deleteIds)` |
73
139
 
@@ -75,7 +141,7 @@ data = applyChanges(data, toggleDone(data, data.tasks[0], now))
75
141
 
76
142
  ## English
77
143
 
78
- Building blocks for a timeline (today / this week / months / this year / life) and projects, taken from the Magic Lamp app. `@shiodome47/planner/core` is available now: the data model (`Task`, `Habit`, `Project`, `PlannerData`) and the rules — which column a dated task belongs to, the next date of a recurring habit ("2nd Sunday of each month", "every December 6"), placing, finishing and reordering, and review helpers. Functions never mutate data; they return `Changes`, which you save wherever you like and apply locally with `applyChanges`. Pass the current time (`now`) explicitly. UI labels are Japanese. Timeline and project screens will follow as `/timeline` and `/projects`.
144
+ Building blocks for a timeline (today / this week / months / this year / life) and projects, taken from the Magic Lamp app. Screens: `<Timeline data now onChange />` (`@shiodome47/planner/timeline`) and `<Projects data now onChange />` (`@shiodome47/planner/projects`); import `@shiodome47/planner/style.css`. Styles apply only inside `.planner`; override `--pl-*` variables to match your app. `@shiodome47/planner/core` holds the data model (`Task`, `Habit`, `Project`, `PlannerData`) and the rules — which column a dated task belongs to, the next date of a recurring habit ("2nd Sunday of each month", "every December 6"), placing, finishing and reordering, and review helpers. Habits can be ended as "graduated" or "paused" (`endHabit` / `resumeHabit`); their check history is kept, they move to a collapsed "past habits" list, and `habitActiveOn` / `habitRecord` count only the days a habit was active. Functions never mutate data; they return `Changes`, which you save wherever you like and apply locally with `applyChanges`. Pass the current time (`now`) explicitly. UI labels are Japanese.
79
145
 
80
146
  ## License
81
147