docs: harmonize component documentation

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": ["Bash(yarn test:*)", "Bash(find:*)"],
+    "deny": [],
+    "ask": []
+  }
+}

.gitignore

@@ -4,6 +4,9 @@
 !.env.example
 node_modules
 
+# Claude Code local settings
+.claude/*.local.json
+
 # Yarn 4 without Zero-installs
 .pnp.*
 .yarn/*

docs/code-review-checklist.md

@@ -10,7 +10,7 @@ When performing code review, double check all of the items below:
 - [ ] All new components, functions and other entities are documented
 - [ ] The repo documentation markdown files are updated if the changes touch upon those.
 - [ ] If the change adds functions available to the user, tracking events are enabled with new ones defined if needed.
-- [ ] Any new Svelte components that have been created, follow the [Svelte component guidelines](contributing.md#svelte-components).
+- [ ] Any new Svelte components that have been created follow the [Svelte component guidelines](contributing.md#svelte-components).
 - [ ] Errors are handled properly and logged in the code.
 - [ ] Troubleshoot any failing checks in the PR.
 - [ ] Check that parts of the application that share dependencies with the PR but are not included in it are not unduly affected.

docs/contributing.md

@@ -379,7 +379,14 @@ let className: $$Props['class'] = $$props['class'];
 
 Follow Svelte's [guidelines for component documentation](https://svelte.dev/docs/faq#how-do-i-document-my-components). For an example, see [`IconBase`](/frontend/src/lib/components/icon/base/IconBase.svelte) component and its associated [type definition](/frontend/src/lib/components/icon/base/IconBase.type.ts).
 
-Place the Svelte docstring at the top of the file, before the `<script>` block.
+Place the Svelte docstring at the top of the file, before the `<script>` block. The documentation must consist of:
+
+- general description
+- 'Properties' (see below)
+- 'Slots' detailing all slots and their uses (if applicable)
+- 'Usage' showing a concise code block of the component’s use
+
+The type file defining the properties is the prime source of truth for the properties’ descriptions. Make sure the "Properties" section of the component doc string matches that.
 
 Add documentation for pages, layouts and other non-reusable components, detailing their main purpose. Include in their documentation under separate subheadings:
 

frontend/src/lib/admin/components/jobs/FeatureJobs.svelte

@@ -1,3 +1,20 @@
+<!--
+@component
+Displays jobs for a specific admin feature, showing active and past job details.
+
+### Properties
+
+- `feature`: The admin feature to display jobs for.
+- `showFeatureLink`: Whether to show the "Go to Feature" link. Default: `true`
+- Any valid attributes of a `<section>` element
+
+### Usage
+
+```tsx
+<FeatureJobs feature={ADMIN_FEATURE.FactorAnalysis} />
+```
+-->
+
 <script lang="ts">
   import { ADMIN_FEATURE } from '$lib/admin/features';
   import { Button } from '$lib/components/button';

frontend/src/lib/admin/components/jobs/JobDetails.svelte

@@ -1,3 +1,19 @@
+<!--
+@component
+Displays detailed information about a job, including its status, progress, and messages.
+
+### Properties
+
+- `job`: The job information to display.
+- Any valid attributes of an `<article>` element
+
+### Usage
+
+```tsx
+<JobDetails job={jobInfo} />
+```
+-->
+
 <script lang="ts">
   import { Button } from '$lib/components/button';
   import ButtonWithConfirmation from '$lib/components/buttonWithConfirmation/ButtonWithConfirmation.svelte';

frontend/src/lib/admin/components/jobs/WithPolling.svelte

@@ -1,8 +1,16 @@
-<!-- @component
-
+<!--
+@component
 A temporary utility component within which jobs are being polled.
 
 TODO[Svelte 5]: Count subscriptions to stores (or $states) and automatically start and stop polling.
+
+### Usage
+
+```tsx
+<WithPolling>
+  <FeatureJobs feature={ADMIN_FEATURE.FactorAnalysis} />
+</WithPolling>
+```
 -->
 
 <script lang="ts">

frontend/src/lib/admin/components/languageFeatures/LanguageSelector.svelte

@@ -1,9 +1,20 @@
-<!--@component
-# Language Selector
+<!--
+@component
+Reusable component for selecting target language for language-based features (question info, argument condensation, etc.). Automatically selected if only one language is available.
 
-Reusable component for selecting target language for language-based features (question info, argument condensation, etc.).
-Automatically selected if only one language is available.
+### Properties
 
+- `selected`: The selected language value.
+- `name`: The name of the form element. Default: `'language'`
+- `id`: The id of the select element.
+- `options`: The available language options.
+- Any valid attributes of a `Select` component
+
+### Usage
+
+```tsx
+<LanguageSelector bind:selected={targetLanguage} />
+```
 -->
 
 <script lang="ts">

frontend/src/lib/candidate/components/logoutButton/LogoutButton.svelte

@@ -8,15 +8,16 @@ Accesses `CandidateContext`.
 
 ### Properties
 
-- `logoutModalTimer`:Time in seconds that the logout modal created by the button waits before automatically logging the user out. Defaults to 30
-- `stayOnPage`: boolean deciding if pressing the button takes the user to the login page or not. Defaults to true
-- Any valid properties of a `<Button>` component.
+- `logoutModalTimer`: The duration in seconds a logout modal will wait before automatically logging the user out. Default: `30`
+- `stayOnPage`: Whether pressing the button takes the user to the login page or not. Default: `false`
+- Any valid properties of a `Button` component
 
 ### Settings
 
 - `entities.hideIfMissingAnswers.candidate`: Affects message shown.
 
 ### Usage
+
 ```tsx
 <LogoutButton />
 ```
@@ -30,10 +31,10 @@ Accesses `CandidateContext`.
   import { logDebugError } from '$lib/utils/logger';
   import type { LogoutButtonProps } from './LogoutButton.type';
 
-  type $$props = LogoutButtonProps;
+  type $$Props = LogoutButtonProps;
 
-  export let stayOnPage: $$props['stayOnPage'] = false;
-  export let logoutModalTimer: $$props['logoutModalTimer'] = 30;
+  export let stayOnPage: $$Props['stayOnPage'] = false;
+  export let logoutModalTimer: $$Props['logoutModalTimer'] = 30;
 
   ////////////////////////////////////////////////////////////////////
   // Get contexts

frontend/src/lib/candidate/components/logoutButton/LogoutButton.type.ts

@@ -6,7 +6,7 @@ export type LogoutButtonProps = Partial<ButtonProps> & {
    */
   logoutModalTimer?: number;
   /**
-   * Whether pressing the button takes the user to the login page or not. @default true
+   * Whether pressing the button takes the user to the login page or not. @default false
    */
   stayOnPage?: boolean;
 };

frontend/src/lib/candidate/components/logoutButton/index.ts

@@ -1 +1,2 @@
 export { default as LogoutButton } from './LogoutButton.svelte';
+export * from './LogoutButton.type';

frontend/src/lib/candidate/components/passwordField/PasswordField.svelte

@@ -3,14 +3,17 @@
 PasswordField is an input box for password that comes with a button to reveal and hide the password
 
 ### Properties
-- `id` : optional id for the input
-- `password` : value of the password, bindable
-- `autoComplete` : autocomplete value for password input
-- `label`: the label for the password field. Defaults to `$t('common.password')`
-- `externalLabel` : whether the label is outside the component and should not be rendered inside
-- `focus`: bindable function to set focus to the password input
+
+- `id`: Optional id for the input.
+- `password`: Bindable: The password value.
+- `autocomplete`: The autocomplete value for password input. Default: `''`
+- `label`: The label for the password field.
+- `externalLabel`: Whether the label is outside the component and should not be rendered inside. Default: `false`
+- `focus`: Bindable: Function to set focus to the password input.
+- Any valid attributes of a `<div>` element
 
 ### Usage
+
 ```tsx
 <PasswordField bind:password={passwordOfContext} autocomplete="current-password" />
 ```
@@ -20,12 +23,15 @@ PasswordField is an input box for password that comes with a button to reveal an
   import { Button } from '$lib/components/button';
   import { getComponentContext } from '$lib/contexts/component';
   import { getUUID } from '$lib/utils/components';
+  import type { PasswordFieldProps } from './PasswordField.type';
+
+  type $$Props = PasswordFieldProps;
 
-  export let id: string | undefined = undefined;
-  export let password = '';
-  export let autocomplete = '';
-  export let label: string | undefined = undefined;
-  export let externalLabel = false;
+  export let id: $$Props['id'] = undefined;
+  export let password: $$Props['password'] = '';
+  export let autocomplete: $$Props['autocomplete'] = '';
+  export let label: $$Props['label'] = undefined;
+  export let externalLabel: $$Props['externalLabel'] = false;
   export function focus(): void {
     input?.focus();
   }

frontend/src/lib/candidate/components/passwordField/PasswordField.type.ts

@@ -0,0 +1,28 @@
+import type { SvelteHTMLElements } from 'svelte/elements';
+
+export type PasswordFieldProps = SvelteHTMLElements['div'] & {
+  /**
+   * Optional id for the input.
+   */
+  id?: string;
+  /**
+   * Bindable: The password value.
+   */
+  password?: string;
+  /**
+   * The autocomplete value for password input. @default ''
+   */
+  autocomplete?: string;
+  /**
+   * The label for the password field.
+   */
+  label?: string;
+  /**
+   * Whether the label is outside the component and should not be rendered inside. @default false
+   */
+  externalLabel?: boolean;
+  /**
+   * Bindable: Function to set focus to the password input.
+   */
+  focus?: () => void;
+};

frontend/src/lib/candidate/components/passwordField/index.ts

@@ -1 +1,2 @@
 export { default as PasswordField } from './PasswordField.svelte';
+export * from './PasswordField.type';

frontend/src/lib/candidate/components/passwordSetter/PasswordSetter.svelte

@@ -8,16 +8,16 @@ Contains the dynamic `PasswordValidator` component.
 
 ### Properties
 
-- `password`: value for the password field
-- `autocomplete`: autocomplete attribute for the password input field
-- `errorMessage`: bindable error message if the password is invalid or doesn't match the confirmation password
-- `valid`: bindable property which can be read to see if the password is valid and the confirmation password matches
-- `reset`: bindable function with which to clear to form
+- `password`: Bindable: The password value.
+- `autocomplete`: The autocomplete attribute for the password input field. Default: `'new-password'`
+- `errorMessage`: Bindable: Error message if the password is invalid or doesn't match the confirmation password.
+- `valid`: Bindable: Whether the password is valid and the confirmation password matches.
+- `reset`: Bindable: Function to clear the form.
+- Any valid attributes of a `<form>` element
 
 ### Usage
 
 ```tsx
-
 <PasswordSetter
   bind:password={password}
   bind:valid={canSubmit}/>
@@ -29,11 +29,14 @@ Contains the dynamic `PasswordValidator` component.
   import { PasswordValidator } from '$candidate/components/passwordValidator';
   import { getComponentContext } from '$lib/contexts/component';
   import { getUUID } from '$lib/utils/components';
+  import type { PasswordSetterProps } from './PasswordSetter.type';
+
+  type $$Props = PasswordSetterProps;
 
-  export let password = '';
-  export let autocomplete = 'new-password';
-  export let errorMessage: string | undefined = undefined;
-  export let valid = false;
+  export let password: $$Props['password'] = '';
+  export let autocomplete: $$Props['autocomplete'] = 'new-password';
+  export let errorMessage: $$Props['errorMessage'] = undefined;
+  export let valid: $$Props['valid'] = false;
   export function reset(): void {
     password = '';
     passwordConfirmation = '';

frontend/src/lib/candidate/components/passwordSetter/PasswordSetter.type.ts

@@ -0,0 +1,24 @@
+import type { SvelteHTMLElements } from 'svelte/elements';
+
+export type PasswordSetterProps = SvelteHTMLElements['form'] & {
+  /**
+   * Bindable: The password value.
+   */
+  password?: string;
+  /**
+   * The autocomplete attribute for the password input field. @default 'new-password'
+   */
+  autocomplete?: string;
+  /**
+   * Bindable: Error message if the password is invalid or doesn't match the confirmation password.
+   */
+  errorMessage?: string;
+  /**
+   * Bindable: Whether the password is valid and the confirmation password matches.
+   */
+  valid?: boolean;
+  /**
+   * Bindable: Function to clear the form.
+   */
+  reset?: () => void;
+};

frontend/src/lib/candidate/components/passwordSetter/index.ts

@@ -1 +1,2 @@
 export { default as PasswordSetter } from './PasswordSetter.svelte';
+export * from './PasswordSetter.type';

frontend/src/lib/candidate/components/passwordValidator/PasswordValidator.svelte

@@ -21,9 +21,11 @@ Therefore, the validity should be also checked on form submit as well and on the
 Accesses validation functions from `@openvaa/app-shared`.
 
 ### Properties
-- `password`: The password to validate
-- `username`: The username used to prevent the password from being too similar
-- `validPassword`: A boolean that is set to true when the password is valid
+
+- `password`: The password to validate.
+- `username`: The username used to prevent the password from being too similar. Default: `''`
+- `validPassword`: Bindable: Whether the password is valid.
+- Any valid attributes of a `<div>` element
 
 ### Usage
 
@@ -42,10 +44,13 @@ When using this component, the `validPassword` property should be bound to a boo
   import { tweened } from 'svelte/motion';
   import { getComponentContext } from '$lib/contexts/component';
   import { assertTranslationKey } from '$lib/i18n/utils/assertTranslationKey';
+  import type { PasswordValidatorProps } from './PasswordValidator.type';
+
+  type $$Props = PasswordValidatorProps;
 
-  export let password = '';
-  export let username = '';
-  export let validPassword = false;
+  export let password: $$Props['password'] = '';
+  export let username: $$Props['username'] = '';
+  export let validPassword: $$Props['validPassword'] = false;
 
   const { t } = getComponentContext();
 

frontend/src/lib/candidate/components/passwordValidator/PasswordValidator.type.ts

@@ -0,0 +1,16 @@
+import type { SvelteHTMLElements } from 'svelte/elements';
+
+export type PasswordValidatorProps = SvelteHTMLElements['div'] & {
+  /**
+   * The password to validate.
+   */
+  password?: string;
+  /**
+   * The username used to prevent the password from being too similar. @default ''
+   */
+  username?: string;
+  /**
+   * Bindable: Whether the password is valid.
+   */
+  validPassword?: boolean;
+};

frontend/src/lib/candidate/components/passwordValidator/index.ts

@@ -1 +1,2 @@
 export { default as PasswordValidator } from './PasswordValidator.svelte';
+export * from './PasswordValidator.type';