Skip to content

Commit cdc9062

Browse files
ZmyslnyZmyslny
committed
feat: 2 states readme
1 parent 543c065 commit cdc9062

File tree

1 file changed

+195
-0
lines changed

1 file changed

+195
-0
lines changed

‎scripts/ColorSchemeSwitchTwoStates/README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Color Scheme Switch - Two States (Light/Dark)
2+
3+
Skrypt do przełączania między dwoma motywami kolorystycznymi: jasnym (light) i ciemnym (dark).
4+
5+
## Co robi ten skrypt?
6+
7+
Skrypt zapewnia funkcjonalność przełączania między jasnym i ciemnym motywem na stronie internetowej, z zachowaniem preferencji użytkownika w `localStorage`. Składa się z dwóch części:
8+
9+
### 1. InitScript - Inicjalizacja motywu przy ładowaniu strony
10+
11+
**Plik:** `init-script.js`
12+
13+
Skrypt uruchamia się **przed wyrenderowaniem strony** (inline w `<head>`), aby uniknąć efektu **FOUC** (Flash of Unstyled Content).
14+
15+
**Działanie:**
16+
- Sprawdza `localStorage.colorScheme` i jeśli użytkownik wcześniej wybrał motyw, go stosuje
17+
- Jeśli brak zapisanej preferencji, sprawdza systemowe ustawienia (`prefers-color-scheme`)
18+
- Dodaje klasę `dark` do `document.documentElement` gdy motyw ciemny jest aktywny
19+
20+
### 2. SwitchScript - Przełączanie motywu
21+
22+
**Plik:** `switch-script.js`
23+
24+
Skrypt umożliwia przełączanie między motywami poprzez skrót klawiszowy (domyślnie klawisz `d`).
25+
26+
**Działanie:**
27+
- Udostępnia funkcję `window.inlineScripts.switchColorScheme()` do programowego przełączania motywu
28+
- Nasłuchuje skrótu klawiszowego (domyślnie `d`) i przełącza motyw
29+
- Zapisuje wybraną preferencję w `localStorage`
30+
- Inteligentnie ignoruje naciśnięcia klawisza gdy fokus jest na polach input, textarea, select lub elementach z contentEditable
31+
32+
## Użycie
33+
34+
### Metoda 1: Przy użyciu klas PHP (zalecane)
35+
36+
**Krok 1:** Dodaj do swojego `AppServiceProvider`:
37+
38+
```php
39+
use Zmyslny\LaravelInlineScripts\Ready\ColorSchemeSwitchTwoStates\InitScript;
40+
use Zmyslny\LaravelInlineScripts\Ready\ColorSchemeSwitchTwoStates\SwitchScript;
41+
42+
class AppServiceProvider extends ServiceProvider
43+
{
44+
public function boot(): void
45+
{
46+
BladeInlineScripts::take(
47+
new InitScript(), // inicjalizuje motyw przy ładowaniu strony
48+
new SwitchScript('d') // przełącza motyw po naciśnięciu klawisza 'd'
49+
)->registerAs('colorSchemeScripts');
50+
}
51+
}
52+
```
53+
54+
**Krok 2:** Wstaw dyrektywę Blade w swoim szablonie:
55+
56+
```blade
57+
<html>
58+
<head>
59+
...
60+
@colorSchemeScripts
61+
</head>
62+
<body>
63+
...
64+
```
65+
66+
**Krok 3 (opcjonalnie):** Dodaj widok z ikonami motywów:
67+
68+
```bash
69+
php artisan vendor:publish --tag=color-scheme-2-states-views
70+
```
71+
72+
Wybierz odpowiedni widok i wstaw go w swoim szablonie:
73+
- Blade + TailwindCss + Hero icons: `../views/color-scheme-switch-two-states/hero-icons-tailwind.blade.php`
74+
- Livewire/Alpine + TailwindCss + Hero icons: `../views/color-scheme-switch-two-states/hero-icons-tailwind-alpine.blade.php`
75+
76+
### Metoda 2: Bezpośrednie użycie plików JS
77+
78+
**Krok 1:** Opublikuj wbudowane skrypty:
79+
80+
```bash
81+
php artisan vendor:publish --tag=color-scheme-2-states-js
82+
```
83+
84+
Skopiuje to skrypty do `resources/js/color-scheme-switch-two-states/[init-script.js, switch-script.js]`.
85+
86+
**Krok 2:** Zarejestruj skrypty w `AppServiceProvider`:
87+
88+
```php
89+
class AppServiceProvider extends ServiceProvider
90+
{
91+
public function boot(): void
92+
{
93+
BladeInlineScripts::takeFiles(
94+
[
95+
resource_path('js/color-scheme-switch-two-states/init-script.js'),
96+
['__DARK__' => 'dark'], // zmienne do zastąpienia w skrypcie
97+
],
98+
[
99+
resource_path('js/color-scheme-switch-two-states/switch-script.js'),
100+
['__DARK__' => 'dark', '__LIGHT__' => 'light', '__TOGGLE_KEY__' => 'd'],
101+
]
102+
)->registerAs('colorSchemeScripts');
103+
}
104+
}
105+
```
106+
107+
**Krok 3:** Wstaw dyrektywę Blade w swoim szablonie (tak samo jak w Metodzie 1).
108+
109+
## Konfiguracja
110+
111+
### Zmiana klawisza przełączania
112+
113+
Domyślnie skrypt używa klawisza `d` do przełączania motywów. Możesz to zmienić przekazując inny klawisz do konstruktora `SwitchScript`:
114+
115+
```php
116+
new SwitchScript('t') // użyj klawisza 't' zamiast 'd'
117+
```
118+
119+
**Wymagania:** Klawisz musi być pojedynczą małą literą (a-z).
120+
121+
### Zmiana nazw klas CSS
122+
123+
Domyślnie skrypt dodaje klasę `dark` do elementu `<html>`. Możesz to zmienić edytując wartości w enumie `SchemeTypeEnum`:
124+
125+
```php
126+
enum SchemeTypeEnum: string
127+
{
128+
case DARK = 'dark';
129+
case LIGHT = 'light';
130+
}
131+
```
132+
133+
Lub przy użyciu bezpośrednich plików JS, zmieniając placeholdery:
134+
135+
```php
136+
['__DARK__' => 'dark-mode', '__LIGHT__' => 'light-mode']
137+
```
138+
139+
## Programowe przełączanie motywu
140+
141+
Skrypt udostępnia funkcję do programowego przełączania motywu:
142+
143+
```javascript
144+
window.inlineScripts.switchColorScheme();
145+
```
146+
147+
Możesz jej użyć np. w obsłudze kliknięcia przycisku:
148+
149+
```html
150+
<button onclick="window.inlineScripts.switchColorScheme()">
151+
Przełącz motyw
152+
</button>
153+
```
154+
155+
## Struktura plików
156+
157+
```
158+
ColorSchemeSwitchTwoStates/
159+
├── InitScript.php # Klasa PHP do inicjalizacji motywu
160+
├── SwitchScript.php # Klasa PHP do przełączania motywu
161+
├── SchemeTypeEnum.php # Enum z wartościami motywów (dark/light)
162+
├── js/
163+
│ ├── init-script.js # Skrypt inicjalizacji (inline w <head>)
164+
│ └── switch-script.js # Skrypt przełączania (inline w <head>)
165+
└── view/
166+
├── hero-icons-tailwind.blade.php # Widok z ikonami (Blade + Tailwind)
167+
└── hero-icons-tailwind-alpine.blade.php # Widok z ikonami (Alpine + Tailwind)
168+
```
169+
170+
## Jak to działa?
171+
172+
1. **Przy ładowaniu strony:** `init-script.js` sprawdza zapisaną preferencję lub preferencje systemowe i natychmiast aplikuje odpowiedni motyw
173+
2. **Przełączanie:** Po naciśnięciu skrótu klawiszowego, `switch-script.js` przełącza klasę `dark` i zapisuje wybór w `localStorage`
174+
3. **Następne wizyty:** Przy kolejnym ładowaniu strony, `init-script.js` odczyta zapisaną preferencję i zastosuje ją przed wyrenderowaniem strony
175+
176+
## Testowanie
177+
178+
Możesz opublikować testy jednostkowe dla skryptów JS:
179+
180+
```bash
181+
php artisan vendor:publish --tag=color-scheme-2-states-js-tests
182+
```
183+
184+
Lub opublikować wszystko naraz (skrypty JS, testy i widoki):
185+
186+
```bash
187+
php artisan vendor:publish --tag=color-scheme-2-states-all
188+
```
189+
190+
## Różnica między Two States a Three States
191+
192+
- **Two States:** Przełączanie między jasnym i ciemnym motywem (2 stany)
193+
- **Three States:** Przełączanie między jasnym, ciemnym i systemowym motywem (3 stany)
194+
195+
Jeśli potrzebujesz opcji "auto/system", użyj wariantu Three States.

0 commit comments

Comments
 (0)