Pengaturan Tampilan

Halaman Account tempat user memilih mode tampilan Light, Dark, atau mengikuti System, dan dirender di dalam Panel tempat user sedang berada.

Ini adalah satu-satunya Settings Page yang sama sekali tidak memiliki state di server. Pilihan tampilan disimpan di browser.

Gunakan dokumentasi ini ketika Anda perlu mengetahui:

• di mana preference tampilan disimpan;
• bagian mana yang membacanya;
• bagaimana theme diterapkan;
• dan bagaimana warna yang dikonfigurasi pada Panel berinteraksi dengan Light/Dark mode.

Contoh Minimal

Tidak ada yang perlu diregistrasikan:

<?php

declare(strict_types=1);

namespace App\Panels\Admin;

use PandaPanel\Core\Panel;
use PandaPanel\Core\PanelProvider;

final class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->path('admin')
            ->auth();
    }
}

Periksa route:

php artisan route:list --name=panel.admin.pages.settings-appearance

Hasil:

GET  admin/settings/appearance  panel.admin.pages.settings-appearance

Class Page

PandaPanel\Pages\Settings\AppearanceSettings extends PandaPanel\Pages\Page dan hanya mengoverride satu method.

Member	Value
$title	'Appearance'
$subheading	'Choose how the interface looks on this device.'
$slug	'settings-appearance'
$component	'panel/settings/Appearance'
$navigationIcon	'palette'
$navigationGroup	'Account'
$navigationSort	30
$middleware	tidak ada
routePath()	'settings/appearance'

Contoh:

use PandaPanel\Pages\Settings\AppearanceSettings;

AppearanceSettings::routeName('admin');
// 'panel.admin.pages.settings-appearance'

AppearanceSettings::url('admin');
// '/admin/settings/appearance'

AppearanceSettings::url('app');
// '/app/settings/appearance'

Signature:

public static function routeName(
    PandaPanel\Core\Panel|string|null $panel = null
): string;

public static function url(
    PandaPanel\Core\Panel|string|null $panel = null
): string;

Class ini tidak mengoverride props().

Base implementation mengembalikan:

[]

Jadi component hanya menerima:

• metadata page;
• shared prop panel.

Tidak ada:

appearance
savedValue
server-side preference
form submission

Apa yang Dirender

File:

resources/js/pages/panel/settings/Appearance.vue

menggunakan PanelLayout dan merender satu component utama:

<script setup lang="ts">
import AppearanceTabs from '@/components/AppearanceTabs.vue';
import { Card, CardContent } from '@/components/ui/card';
import PanelLayout from '@/panel/layouts/PanelLayout.vue';

defineOptions({ layout: PanelLayout });

defineProps<{ page: PageMetadata }>();
</script>

<template>
    <Card>
        <CardContent>
            <AppearanceTabs />
        </CardContent>
    </Card>
</template>

AppearanceTabs.vue menampilkan tiga pilihan:

Light
Dark
System

Saat user memilih salah satunya, component memanggil:

updateAppearance(value)

Tidak terjadi:

• HTTP request;
• flash message;
• reload;
• submit ke server.

Composable

File:

resources/js/composables/useAppearance.ts

disediakan package dan dipublish ke path yang sama pada application.

API:

export type Appearance =
    | 'light'
    | 'dark'
    | 'system';

export type ResolvedAppearance =
    | 'light'
    | 'dark';

export type UseAppearanceReturn = {
    appearance: Ref<Appearance>;
    resolvedAppearance: ComputedRef<ResolvedAppearance>;
    updateAppearance: (value: Appearance) => void;
};

export function useAppearance(): UseAppearanceReturn;
export function updateTheme(value: Appearance): void;
export function initializeTheme(): void;

Appearance dan ResolvedAppearance juga dire-export melalui:

@/types

Export	Fungsi
useAppearance()	Membaca preference yang tersimpan saat mount dan mengembalikan state serta setter
updateAppearance(value)	Menulis ke localStorage, cookie, lalu menerapkan theme
resolvedAppearance	Me-resolve system melalui matchMedia('(prefers-color-scheme: dark)')
updateTheme(value)	Menambah/menghapus class dark pada document.documentElement
initializeTheme()	Menerapkan stored preference saat boot dan mendaftarkan listener perubahan theme OS

Contoh:

<script setup lang="ts">
import { useAppearance } from '@/composables/useAppearance';

const {
    appearance,
    resolvedAppearance,
    updateAppearance,
} = useAppearance();
</script>

<template>
    <button @click="updateAppearance('dark')">
        Dark
    </button>

    <p>
        Currently {{ appearance }},
        rendering as {{ resolvedAppearance }}.
    </p>
</template>

initializeTheme()

initializeTheme() seharusnya dijalankan dari entry Inertia application sebelum UI selesai dimount.

// resources/js/app.ts

import {
    initializeTheme,
} from '@/composables/useAppearance';

createInertiaApp({
    // ...
});

initializeTheme();

Tanpa ini, preference baru diterapkan setelah component yang menggunakan useAppearance() mencapai onMounted().

Akibatnya dapat terjadi:

Stored Theme = Dark
       ↓
First Paint = Light
       ↓
Vue Mounted
       ↓
Theme berubah menjadi Dark

User akan melihat flash singkat dengan theme yang salah.

Selain itu listener matchMedia() untuk mode system tidak akan didaftarkan.

Tempat Preference Disimpan

Dua tempat digunakan untuk dua pembaca yang berbeda:

Storage	Key	Ditulis oleh	Dibaca oleh
localStorage	appearance	updateAppearance()	useAppearance() dan initializeTheme()
Cookie	appearance, path=/, max-age 365 hari, SameSite=Lax	updateAppearance()	Server-side rendering agar first paint menggunakan theme yang benar

Tidak ada data yang:

• ditulis ke database;
• dikirim ke route Panel;
• disimpan pada User Model.

Artinya preference bersifat per browser/device, bukan per user account.

User yang sama pada device lain akan kembali menggunakan:

system

Class yang Diterapkan

Hasil akhirnya adalah:

document.documentElement.classList.toggle(
    'dark',
    systemTheme === 'dark',
);

Tailwind menggunakan class tersebut untuk dark variant.

Toggle pada Panel Header

PanelHeader.vue menggunakan composable yang sama:

const {
    appearance,
    updateAppearance,
} = useAppearance();

const isDark = computed(
    () => appearance.value === 'dark',
);

function toggleAppearance(): void {
    updateAppearance(
        isDark.value
            ? 'light'
            : 'dark',
    );
}

Header toggle hanya berpindah:

light ↔ dark

Ia tidak dapat memilih system.

User yang ingin kembali ke mode system harus membuka halaman Appearance Settings.

Warna Milik Panel

Appearance dan Panel Theme adalah dua concern berbeda.

Appearance menentukan:

Light / Dark

Sedangkan Panel menentukan palette.

API:

public function colors(
    array $light,
    array $dark = []
): self;

public function getTheme(): array;
// [
//     'light' => [...],
//     'dark' => [...],
// ]

Contoh:

$panel->colors(
    light: [
        'primary' => 'oklch(0.55 0.18 265)',
        'sidebar' => '#f8fafc',
    ],

    dark: [
        'primary' => 'oklch(0.72 0.15 265)',
    ],
);

Value menjadi CSS custom properties.

PandaPanel\Support\PanelTheme memvalidasinya terhadap:

• 18 nama property yang diizinkan;
• empat bentuk value.

Format warna yang didukung:

hex
rgb()
hsl()
oklch()

Value invalid dibuang, bukan membuat Panel gagal dirender.

panel.theme

Kedua map dikirim ke frontend melalui:

panel.theme

usePanelStyling() menerapkan Light map sebagai inline custom properties:

for (
    const [property, value]
    of Object.entries(theme.light ?? {})
) {
    style[`--${property}`] = value;
}

Dark map dikirim tetapi tidak diterapkan inline.

Alasannya inline style tidak dapat memiliki conditional selector atau media query.

Jika palette harus berbeda berdasarkan Light/Dark scheme, gunakan stylesheet yang dimuat melalui:

Panel::assets()

Dark Mode Flag

API:

public function darkMode(
    bool $darkMode = true
): self;

public function hasDarkMode(): bool;
// true secara default

Value dikirim sebagai:

panel.darkMode

Shell bawaan saat ini tidak menjadikan flag tersebut sebagai syarat untuk merender Header Toggle.

Jadi:

$panel->darkMode(false);

lebih merupakan declaration yang dapat dibaca oleh custom component Anda.

Misalnya custom topbar dapat memilih untuk tidak menampilkan theme toggle.

Mematikan Halaman

$panel->settings(false);

Settings bersifat all-or-nothing.

Yang dimatikan sekaligus:

Profile
Security
Appearance

Jika Panel seperti kiosk tidak ingin menyediakan theme preference, matikan built-in settings dan daftarkan custom account page sendiri bila dibutuhkan.

Testing

Tidak ada server state yang perlu diuji.

Yang diuji adalah apakah Page dirender dengan shell dan component yang benar.

use Inertia\Testing\AssertableInertia;

it(
    'renders the appearance settings page with no server state',
    function (): void {
        $this
            ->actingAs($user)
            ->get('/app/settings/appearance')
            ->assertOk()
            ->assertInertia(
                fn (AssertableInertia $page) =>
                    $page
                        ->component(
                            'panel/settings/Appearance'
                        )
                        ->where(
                            'panel.id',
                            'app'
                        )
            );
    }
);

Test terkait berada di:

tests/Feature/Panel/PanelSettingsTest.php

Hal yang Perlu Diperhatikan

• Preference bersifat per device, bukan per user. Local storage dan cookie hanya berlaku pada browser tersebut.
• vendor:publish tidak overwrite secara default. Jika starter kit sudah memiliki useAppearance.ts, file PandaBear dilewati kecuali menggunakan --force.
• Tanpa initializeTheme(), first paint dapat salah.
• Header toggle tidak pernah memilih system.
• panel.theme.dark dikirim tetapi tidak diterapkan inline.
• Route hanya GET. POST menghasilkan 405.
• Panel access tetap berlaku. User yang tidak boleh memasuki Panel mendapat 403; guest diarahkan ke login.

Lihat Juga

• Profile Settings
• Security Settings
• Settings Pages
• Panel Branding
• Tailwind Theme
• CSS Hooks
• Custom Shell
• Frontend Assets