@shiodome47/planner 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 shiodome47
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,134 @@
1
- # Temporary Holding Version
1
+ # @shiodome47/planner
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 時間軸(今日・今週・数か月・今年・一生)とプロジェクトの部品です。[まほうのランプ](https://lamp.shiodome47.com) の仕組みを、ほかのアプリでも使えるように取り出しました。
4
+
5
+ | 入り口 | 中身 | 状態 |
6
+ |---|---|---|
7
+ | `@shiodome47/planner/core` | **土台**。データの形と決まりごと(画面なし。計算だけ) | ✅ 使えます |
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` の中だけに効く) | ✅ |
11
+
12
+ 時間軸とプロジェクトは、同じ「やること」の一覧を見ています。期日を入れたやることは、プロジェクトのカードにも、時間軸の列にも出ます。つなぐのは画面ではなく、この土台(`core`)です。
13
+
14
+ ```bash
15
+ npm install @shiodome47/planner
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
+ 見た目は `.planner` の中だけに効き、色は変数で決まります。使う側の CSS で上書きすると、アプリの色に合わせられます。
54
+
55
+ ```css
56
+ .planner {
57
+ --pl-accent: #2563eb; /* 決定のボタン・今日の列・ドラッグの線 */
58
+ --pl-panel: #fff; /* 列・カード */
59
+ --pl-panel-2: #f3f4f6; /* 入力欄・行にマウスを乗せたとき */
60
+ --pl-border: #e5e7eb;
61
+ --pl-text: #111827;
62
+ --pl-muted: #6b7280;
63
+ --pl-sticky-top: 56px; /* 上に固定の見出しがあるページでは、その高さ */
64
+ }
65
+ ```
66
+
67
+ ほかに `--pl-page-bg`・`--pl-accent-text`・`--pl-danger`・`--pl-warning`・`--pl-ok` があります。プロジェクトの色は `PROJECT_COLORS`(`teal`・`blue` など 8 色)。
68
+
69
+ ## 土台(core)
70
+
71
+ ### データの形
72
+
73
+ ```ts
74
+ import type { PlannerData, Task, Habit, Project } from '@shiodome47/planner/core'
75
+
76
+ const data: PlannerData = { tasks: [], habits: [], projects: [] }
77
+ ```
78
+
79
+ | 形 | 中身 |
80
+ |---|---|
81
+ | `Task` | やること。`horizon`(列)・`priority`(A〜D・P)・`due`(期日 YYYY-MM-DD)・`projectId` など |
82
+ | `Habit` | 習慣(くり返し)。`period`(毎日・毎週・毎月・毎年)と「その日」(`weekday`・`day`・`yearDay`) |
83
+ | `Project` | プロジェクト・テーマ。テーマの中にプロジェクトを入れられる(1 段だけ) |
84
+
85
+ アプリは、`PlannerData` に自分の項目(日記など)を足した形で持って構いません。土台の関数は、足した項目を変えずに残します。
86
+
87
+ ### 変更は「返す」だけ。保存はアプリが行う
88
+
89
+ 関数はデータを直接は書き換えず、**変更(`Changes`)を返します**。アプリはそれを保存先に書き、`applyChanges` で手元のデータにも当てます。保存先(IndexedDB・サーバー・同期)は自由に選べます。
90
+
91
+ ```ts
92
+ import { applyChanges, buildColumns, newTask, newHabit, withDay, toggleDone, HORIZON_NAME } from '@shiodome47/planner/core'
93
+
94
+ const now = new Date()
95
+
96
+ // 期日つきのやること → 期日から、出す列が自動で決まる(2 日後なら「今週」)
97
+ data = applyChanges(data, { tasks: [newTask(data, { title: '総会の資料をつくる', horizon: 'pool', priority: 'B', due: '2026-11-21' }, now)] })
98
+
99
+ // くり返し: 毎月 第 2 日曜 → その日がある週は「今週」、その日は「今日」の列にも自動で出る
100
+ data = applyChanges(data, { habits: [withDay(newHabit(data, { title: '役員会', period: 'month' }, now), 'w2-0')] })
101
+
102
+ // 列ごとに並べる(番号 A1・B1 … も付く)
103
+ for (const col of buildColumns(data, now)) {
104
+ console.log(HORIZON_NAME[col.horizon], col.tasks.map((v) => `${v.label} ${v.task.title}`))
105
+ }
106
+
107
+ // 終える
108
+ data = applyChanges(data, toggleDone(data, data.tasks[0], now))
109
+ ```
110
+
111
+ 「今」(`now`)は、関数に渡します。テストしやすく、2 台の端末で結果がずれないようにするためです。日付が変わっても保存してあるデータは書き換えず、表示するときに判断します(同期で競合しないように)。
112
+
113
+ ### おもな関数
114
+
115
+ | 分類 | 関数 |
116
+ |---|---|
117
+ | 時間軸 | `buildColumns(data, now)` 列ごとの表示(やること・習慣・明日の欄・来週の欄)/`horizonForDue(due, now)` 期日から列/`effectiveHorizon(task, now)` |
118
+ | やること | `newTask` `toggleDone` `placeDown`(今日やる、などで下ろす)`returnUp` `moveTo` `moveStep` `setPriority` `setDue` `removeTask` `reorderTasks` `postponeToTomorrow` `bringToToday` |
119
+ | 習慣 | `newHabit` `toggleHabit` `toggleHabitAll` `placeHabitDown` `habitToTask` `reorderHabits` |
120
+ | くり返しの「その日」 | 毎月: `withDay(habit, 20 \| 'end' \| 'w2-3' \| 'wL-5')`/毎週・毎年: `withWhen(habit, 3 \| '12-06' \| '12')`/`whenLabel` `whenDate` `monthDayDate` |
121
+ | プロジェクト | `newProject` `topProjects` `childProjects` `moveProject` `removeProject` `reorderProjects` `projectGoals` `reorderGoals` |
122
+ | 振り返り | `doneOn(data, day, now)` その日に済ませたこと/`streak(habit, now)` 続いた日数/`toggleHabitOnDay` `finishOnDay`(過ぎた日に付け直す) |
123
+ | 日付 | `dayKey` `weekKey` `weekStart` `addDays` `periodLabel` `dueLabel` `shortDueLabel` |
124
+ | 当てる | `applyChanges(data, changes)` / `mergeById(list, puts, deleteIds)` |
125
+
126
+ 画面の言葉(`HORIZON_NAME`・`PRIORITY_NAME`・`PERIOD_NAME` など)は日本語です。
127
+
128
+ ## English
129
+
130
+ 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. 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.
131
+
132
+ ## License
133
+
134
+ MIT