Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

refactor(frontend): delete helpers, hooks and types nothing uses

spacesdrive65a500d9b9e0
diff --git a/docs/architecture/frontend/DESIGN_SYSTEM.md b/docs/architecture/frontend/DESIGN_SYSTEM.md
index e06c395..0359329 100644
--- a/docs/architecture/frontend/DESIGN_SYSTEM.md
+++ b/docs/architecture/frontend/DESIGN_SYSTEM.md
@@ -87,7 +87,7 @@ The interface follows the UI/UX Design Intelligence system: the Laws of UX, WCAG
- Focus: text boxes (`Input`, `Textarea`, `SelectTrigger`, `InputGroup`, `SearchField`) show it quietly, as the border in the focus colour with a faint halo (`focus-visible:border-ring focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/15`); buttons, links and every other control keep the global 2 px outline. Copy the box style for any new text box.
- WCAG 2.2 AA is the floor: every action works by keyboard with a visible focus ring, every control has a name that contains its visible label, colour is never the only signal (status, trend, links in text, chart series), and status changes are announced (`LiveStatus`, `role="alert"` for a message that appears after an action; static `Alert` notes stay silent).
-- Each page has a title in the browser tab (detail pages name the item with `useDocumentTitle(name)`), focus moves to the `PageHeader` heading after navigation (add no other focus target), and the view (tab, search, filters, sort, page, layout) lives in the address through `useUrlState`, so Back, refresh and a shared link show the same view.
+- Each page has a title in the browser tab (detail pages name the item with `useDocumentTitle(name)`), focus moves to the `PageHeader` heading after navigation (add no other focus target), and the view (tab, search, filters, sort, page, layout) lives in the address through `useUrlChoice` or `useLibraryParams`, so Back, refresh and a shared link show the same view.
- One primary (default) button per view. An empty state's action replaces the header action, it does not repeat it.
- Every data view designs loading, empty, error, partial failure and stale states, and says how old cached data is. Refreshing keeps the data on screen with a progress bar; skeletons are only for the first load.
- Metric tiles say what period they cover, show the exact value behind a rounded one, and colour a change by whether it is good, with the direction in words for screen readers.
diff --git a/docs/guidelines/UI_UX.md b/docs/guidelines/UI_UX.md
index 43112d3..8d90eac 100644
--- a/docs/guidelines/UI_UX.md
+++ b/docs/guidelines/UI_UX.md
@@ -74,7 +74,7 @@ Don't cite these as rules: "7 plus or minus 2" as a menu limit, the 400 ms figur
### Navigation and layout
- Each page has its own tab title (`useDocumentTitle` for detail pages), focus moves to its heading after navigation, and the current place is marked (`aria-current`).
-- View state lives in the address (`useUrlState`, `useUrlChoice`, `useUrlPage`): tabs, search, filters, sort, page, layout. Typing replaces the history entry; a tab or page change adds one.
+- View state lives in the address (`useUrlChoice` in `hooks/use-url-state.ts` for tabs and choices, `useLibraryParams` for a library's search, filters, sort and page; both build on `lib/urlState.ts`): tabs, search, filters, sort, page, layout. Typing replaces the history entry; a tab or page change adds one.
- One label per destination, the same in the sidebar, the page title, buttons and the command palette.
- Page anatomy stays the same everywhere: `PageHeader` (title, short description, the primary action on the right), then filters, then content.
diff --git a/frontend/src/features/analytics/useLibraryParams.ts b/frontend/src/features/analytics/useLibraryParams.ts
index 8ff57fa..11983c0 100644
--- a/frontend/src/features/analytics/useLibraryParams.ts
+++ b/frontend/src/features/analytics/useLibraryParams.ts
@@ -2,8 +2,6 @@ import { useCallback } from 'react';
import { useSearchParams } from 'react-router-dom';
import { readParam, readPositiveInt, withParam } from '@/lib/urlState';
-export type ParamDefaults = Record<string, string>;
-
export interface UpdateOptions {
// typing replaces the history entry instead of adding one per keystroke
replace?: boolean;
diff --git a/frontend/src/features/automations/automationData.ts b/frontend/src/features/automations/automationData.ts
index dbed7fc..272def7 100644
--- a/frontend/src/features/automations/automationData.ts
+++ b/frontend/src/features/automations/automationData.ts
@@ -362,11 +362,6 @@ export function ruleFormError(form: RuleForm): RuleFieldProblem | null {
return null;
}
-// the message of the first problem, or null
-export function ruleFormProblem(form: RuleForm): string | null {
- return ruleFormError(form)?.message ?? null;
-}
-
// a followers-only rule that is on needs Instagram to send the account's messages as well as its comments
export function needsMessageEvents(rules: Pick<AutomationRule, 'accountId' | 'enabled' | 'requireFollow'>[], accountId: string): boolean {
return rules.some(rule => rule.accountId === accountId && rule.enabled && rule.requireFollow);
diff --git a/frontend/src/features/publishing/publishHelpers.ts b/frontend/src/features/publishing/publishHelpers.ts
index e1ea50c..34e180a 100644
--- a/frontend/src/features/publishing/publishHelpers.ts
+++ b/frontend/src/features/publishing/publishHelpers.ts
@@ -206,34 +206,10 @@ export function editPostProblem({ postId, date, time, now }: EditPostCheck): Fie
return null;
}
-export function singlePostError({ selectedAccount, file, contentType, hasCloudConfig, fields, now }: SinglePostCheck): string {
- if (!selectedAccount || !file || !contentType) return 'Choose an account, a content type and a file before publishing.';
- if (!hasCloudConfig) return 'Cloudinary is not set up on the server. Check Settings.';
- if (!fields.scheduleMode) return '';
- if (!fields.scheduleDate || !fields.scheduleTime) return 'Set a date and time for the scheduled post.';
- if (new Date(`${fields.scheduleDate}T${fields.scheduleTime}`) <= now) return 'Pick a time in the future.';
- return '';
-}
-
export function bulkBaseTime(settings: Pick<BulkSettings, 'scheduleMode' | 'startDate' | 'startTime'>): Date | null {
return settings.scheduleMode ? new Date(`${settings.startDate}T${settings.startTime}`) : null;
}
-export function bulkStartError({ settings, fileCount, hasCloudConfig, now }: BulkStartCheck): string {
- if (!settings.account || fileCount === 0 || !settings.contentType) return 'Choose an account, a content type and at least one file.';
- if (!hasCloudConfig) return 'Cloudinary is not set up on the server. Check Settings.';
- if (settings.scheduleMode && (!settings.startDate || !settings.startTime)) return 'Set a start date and time for the schedule.';
- const baseTime = bulkBaseTime(settings);
- if (baseTime && baseTime <= now) return 'Pick a start time in the future.';
- return '';
-}
-
-export function editPostError({ postId, date, time, now }: EditPostCheck): string {
- if (!postId || !date || !time) return 'Set a date and time.';
- if (new Date(`${date}T${time}`) <= now) return 'Pick a time in the future.';
- return '';
-}
-
export function bulkScheduledTime(baseTime: Date, offset: number, intervalMinutes: number): Date {
return new Date(baseTime.getTime() + offset * intervalMinutes * MINUTE_MS);
}
diff --git a/frontend/src/features/publishing/singlePostFlow.ts b/frontend/src/features/publishing/singlePostFlow.ts
index 375af9b..bf97384 100644
--- a/frontend/src/features/publishing/singlePostFlow.ts
+++ b/frontend/src/features/publishing/singlePostFlow.ts
@@ -5,7 +5,7 @@ import type { CloudinaryUploadConfig, UploadError } from '../../services/api';
import type { AccountPostDetails, ContentTypeValue, SinglePostFields } from './publishHelpers.ts';
import type { PublishStatus } from './queueHelpers.ts';
-// singlePostError has already checked that file and contentType are set
+// singlePostProblem has already checked that file and contentType are set
export interface SinglePostInput {
selectedAccount: string;
contentType: ContentTypeValue | '';
diff --git a/frontend/src/features/settings/useClaudeAccess.ts b/frontend/src/features/settings/useClaudeAccess.ts
index e0cc252..58b930e 100644
--- a/frontend/src/features/settings/useClaudeAccess.ts
+++ b/frontend/src/features/settings/useClaudeAccess.ts
@@ -95,5 +95,3 @@ export function useClaudeAccess(showToast: ShowToast) {
creating, createToken, revokingId, revokeToken, revokeClient,
};
}
-
-export type ClaudeAccessState = ReturnType<typeof useClaudeAccess>;
diff --git a/frontend/src/hooks/use-url-state.ts b/frontend/src/hooks/use-url-state.ts
index 4fbe146..9f0377e 100644
--- a/frontend/src/hooks/use-url-state.ts
+++ b/frontend/src/hooks/use-url-state.ts
@@ -1,22 +1,12 @@
import { useCallback } from 'react';
import { useSearchParams } from 'react-router-dom';
-import { readChoice, readParam, readPositiveInt, withParam } from '@/lib/urlState';
+import { readChoice, withParam } from '@/lib/urlState';
export interface UrlStateOptions {
// typing replaces the history entry; a tab or page change adds one so Back returns to it
history?: 'push' | 'replace';
}
-export function useUrlState(key: string, fallback = '', { history = 'replace' }: UrlStateOptions = {}) {
- const [params, setParams] = useSearchParams();
- const value = readParam(params, key, fallback);
- const setValue = useCallback(
- (next: string) => setParams(current => withParam(current, key, next, fallback), { replace: history === 'replace' }),
- [setParams, key, fallback, history],
- );
- return [value, setValue] as const;
-}
-
export function useUrlChoice<T extends string>(key: string, choices: readonly T[], fallback: T, { history = 'push' }: UrlStateOptions = {}) {
const [params, setParams] = useSearchParams();
const value = readChoice(params, key, choices, fallback);
@@ -26,13 +16,3 @@ export function useUrlChoice<T extends string>(key: string, choices: readonly T[
);
return [value, setValue] as const;
}
-
-export function useUrlPage(key = 'page', { history = 'push' }: UrlStateOptions = {}) {
- const [params, setParams] = useSearchParams();
- const value = readPositiveInt(params, key, 1);
- const setValue = useCallback(
- (next: number) => setParams(current => withParam(current, key, String(next), '1'), { replace: history === 'replace' }),
- [setParams, key, history],
- );
- return [value, setValue] as const;
-}
diff --git a/frontend/src/lib/chart.ts b/frontend/src/lib/chart.ts
index ad0d628..59ce31d 100644
--- a/frontend/src/lib/chart.ts
+++ b/frontend/src/lib/chart.ts
@@ -8,10 +8,6 @@ export const SERIES = {
deep: 'var(--chart-5)',
};
-export const SERIES_ORDER = [SERIES.primary, SERIES.neutral, SERIES.warm, SERIES.cool, SERIES.deep];
-
-export const seriesAt = (index: number): string => SERIES_ORDER[index % SERIES_ORDER.length];
-
// a figure is a category name and its value; the summary is what a sighted reader takes from the plot at a glance
export interface ChartPoint {
name: string;
diff --git a/frontend/src/lib/metricIcons.ts b/frontend/src/lib/metricIcons.ts
index 21be10b..0c7a59e 100644
--- a/frontend/src/lib/metricIcons.ts
+++ b/frontend/src/lib/metricIcons.ts
@@ -32,7 +32,5 @@ export const METRIC_ICONS = {
time: Clock,
} satisfies Record<string, LucideIcon>;
-export type MetricIconName = keyof typeof METRIC_ICONS;
-
// Instagram content types, with the same icons wherever they are counted or filtered
export const IG_TYPE_ICONS = { reel: Clapperboard, post: Image, video: Video } satisfies Record<string, LucideIcon>;
diff --git a/frontend/src/utils/formatters.ts b/frontend/src/utils/formatters.ts
index 825d37b..78cdecc 100644
--- a/frontend/src/utils/formatters.ts
+++ b/frontend/src/utils/formatters.ts
@@ -41,11 +41,6 @@ export function fmtDateTime(d: DateLike): string {
});
}
-export function fmtDateShort(d: DateLike): string {
- if (!d) return '';
- return new Date(d).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
-}
-
export function fmtDuration(seconds: number | null | undefined): string {
if (!seconds) return '0:00';
const hours = Math.floor(seconds / 3600);
diff --git a/frontend/tests/features/automations/automationData.test.ts b/frontend/tests/features/automations/automationData.test.ts
index 5e4ff2b..5b3034d 100644
--- a/frontend/tests/features/automations/automationData.test.ts
+++ b/frontend/tests/features/automations/automationData.test.ts
@@ -3,13 +3,16 @@ import assert from 'node:assert/strict';
import {
ACTIVITY_FILTERS, DEFAULT_FOLLOW_PROMPT, DEFAULT_NOT_FOLLOWING, DEFAULT_PUBLIC_REPLY, MAX_MESSAGE_BYTES, accountStatus, canRetry, canRetryPublic,
composeReply, emptyRuleForm, formToRequest, gateDetail, matchModeLabel, messageBytes, needsMessageEvents, parseKeywords, periodStart,
- publicReplyTexts, publicStatusDisplay, ruleFormProblem, ruleFormError, normalizeLink, ruleScopeLabel, ruleToForm, statusDisplay, summarizeStats,
+ publicReplyTexts, publicStatusDisplay, ruleFormError, normalizeLink, ruleScopeLabel, ruleToForm, statusDisplay, summarizeStats,
} from '../../../src/features/automations/automationData.ts';
import type { RuleForm } from '../../../src/features/automations/automationData.ts';
import type { AutomationAccountState, AutomationRule } from '../../../../shared/types/automation.ts';
const NOW = Date.parse('2026-10-16T12:00:00Z');
+// the message of the first problem, or null
+const ruleFormProblem = (rule: RuleForm): string | null => ruleFormError(rule)?.message ?? null;
+
function form(overrides: Partial<RuleForm> = {}): RuleForm {
return { ...emptyRuleForm('ig1'), name: 'Guide', keywordsText: 'GUIDE', replyText: 'Here it is', ...overrides };
}
diff --git a/frontend/tests/features/publishing/publishHelpers.test.ts b/frontend/tests/features/publishing/publishHelpers.test.ts
index baf0b46..3d62fb4 100644
--- a/frontend/tests/features/publishing/publishHelpers.test.ts
+++ b/frontend/tests/features/publishing/publishHelpers.test.ts
@@ -2,7 +2,7 @@ import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
parseUserTags, parseCollaborators, buildScheduledPostPayload, buildContainerPayload, bulkPostDetails,
- singleUploadMessage, singlePostError, bulkStartError, bulkBaseTime, editPostError, bulkScheduledTime,
+ singleUploadMessage, bulkBaseTime, bulkScheduledTime,
singlePostProblem, bulkStartProblem, editPostProblem, thumbOffsetMs, instagramUsername,
} from '../../../src/features/publishing/publishHelpers.ts';
import type { AccountPostDetails, BulkSettings, UploadFailure } from '../../../src/features/publishing/publishHelpers.ts';
@@ -84,23 +84,25 @@ test('single post checks run in order', () => {
const now = new Date('2030-05-01T00:00:00');
const base = { selectedAccount: 'a', file: {} as File, contentType: 'IMAGE', hasCloudConfig: true, now };
const fields = { scheduleMode: true, scheduleDate: '2030-05-02', scheduleTime: '09:00' };
- assert.equal(singlePostError({ ...base, file: null, fields }), 'Choose an account, a content type and a file before publishing.');
- assert.equal(singlePostError({ ...base, hasCloudConfig: false, fields }), 'Cloudinary is not set up on the server. Check Settings.');
- assert.equal(singlePostError({ ...base, fields: { ...fields, scheduleTime: '' } }), 'Set a date and time for the scheduled post.');
- assert.equal(singlePostError({ ...base, fields: { ...fields, scheduleDate: '2030-04-30' } }), 'Pick a time in the future.');
- assert.equal(singlePostError({ ...base, fields }), '');
- assert.equal(singlePostError({ ...base, fields: { scheduleMode: false } as ScheduleFieldValues }), '');
+ const message = (check: Parameters<typeof singlePostProblem>[0]) => singlePostProblem(check)?.message ?? '';
+ assert.equal(message({ ...base, file: null, fields }), 'Choose the file to post.');
+ assert.equal(message({ ...base, hasCloudConfig: false, fields }), 'Uploads are not set up on this server yet. The administrator needs to add the Cloudinary settings.');
+ assert.equal(message({ ...base, fields: { ...fields, scheduleTime: '' } }), 'Set the date and time to publish the post.');
+ assert.equal(message({ ...base, fields: { ...fields, scheduleDate: '2030-04-30' } }), 'Pick a time in the future.');
+ assert.equal(message({ ...base, fields }), '');
+ assert.equal(message({ ...base, fields: { scheduleMode: false } as ScheduleFieldValues }), '');
});
test('bulk start checks run in order', () => {
const now = new Date('2030-04-30T00:00:00');
const base = { settings: bulkSettings, fileCount: 2, hasCloudConfig: true, now };
- assert.equal(bulkStartError({ ...base, fileCount: 0 }), 'Choose an account, a content type and at least one file.');
- assert.equal(bulkStartError({ ...base, hasCloudConfig: false }), 'Cloudinary is not set up on the server. Check Settings.');
- assert.equal(bulkStartError({ ...base, settings: { ...bulkSettings, startTime: '' } }), 'Set a start date and time for the schedule.');
- assert.equal(bulkStartError({ ...base, now: new Date('2031-01-01T00:00:00') }), 'Pick a start time in the future.');
- assert.equal(bulkStartError(base), '');
- assert.equal(bulkStartError({ ...base, settings: { ...bulkSettings, scheduleMode: false } }), '');
+ const message = (check: Parameters<typeof bulkStartProblem>[0]) => bulkStartProblem(check)?.message ?? '';
+ assert.equal(message({ ...base, fileCount: 0 }), 'Add at least one file.');
+ assert.equal(message({ ...base, hasCloudConfig: false }), 'Uploads are not set up on this server yet. The administrator needs to add the Cloudinary settings.');
+ assert.equal(message({ ...base, settings: { ...bulkSettings, startTime: '' } }), 'Set the date and time of the first post.');
+ assert.equal(message({ ...base, now: new Date('2031-01-01T00:00:00') }), 'Pick a start time in the future.');
+ assert.equal(message(base), '');
+ assert.equal(message({ ...base, settings: { ...bulkSettings, scheduleMode: false } }), '');
});
test('bulk base time only exists in schedule mode', () => {
@@ -110,9 +112,10 @@ test('bulk base time only exists in schedule mode', () => {
test('editing a scheduled post needs a future date and time', () => {
const now = new Date('2030-05-01T00:00:00');
- assert.equal(editPostError({ postId: null, date: '2030-05-02', time: '08:00', now }), 'Set a date and time.');
- assert.equal(editPostError({ postId: 'p', date: '2030-04-02', time: '08:00', now }), 'Pick a time in the future.');
- assert.equal(editPostError({ postId: 'p', date: '2030-05-02', time: '08:00', now }), '');
+ const message = (check: Parameters<typeof editPostProblem>[0]) => editPostProblem(check)?.message ?? '';
+ assert.equal(message({ postId: null, date: '2030-05-02', time: '08:00', now }), 'Set the date.');
+ assert.equal(message({ postId: 'p', date: '2030-04-02', time: '08:00', now }), 'Pick a time in the future.');
+ assert.equal(message({ postId: 'p', date: '2030-05-02', time: '08:00', now }), '');
});
test('bulk posts are spaced by the interval', () => {